dkey-lib

A TypeScript library for encrypted file sharing with zero-knowledge proofs on blockchain. Enables secure, decentralized file distribution with cryptographic access control.

Features

• 🔐 Encrypted File Sharing: Encrypt files using BN254 elliptic curve cryptography
• 🔑 Zero-Knowledge Proofs: Generate and verify ZK proofs for secure key distribution
• 📦 IPFS Integration: Store encrypted files and metadata on IPFS
• ⛓️ Blockchain Integration: Deploy listings, place bids, and manage DKeys on Ethereum-compatible chains
• 🔄 Profile Management: Serialize and encrypt user profiles for secure storage
• 🎯 TypeScript Support: Full TypeScript definitions included

Installation

npm install dkey-lib

Prerequisites

• Node.js 18+
• A wagmi config for blockchain interactions
• Access to supported blockchain networks (Base, Ethereum, etc.)

Browser bundle

For plain JS/HTML/CSS frontends without a bundler, use the browser build. Load it with a script tag:

<!-- From node_modules (if you npm install dkey-lib) -->
<script src="node_modules/dkey-lib/dist/dkey-lib.browser.js"></script>

The API is exposed on window.dkeyLib:

• Default export (the dkey object): window.dkeyLib.default or window.dkeyLib.dkey
• Named exports: window.dkeyLib.DkeyUserProfile, window.dkeyLib.Listing, window.dkeyLib.ListingMetadata, window.dkeyLib.Bid, window.dkeyLib.DKey, window.dkeyLib.RESULTS, window.dkeyLib.BidLite

You must still copy the circuits folder from node_modules/dkey-lib/circuits to your public directory and configure paths:

<script>
  window.dkeyLib.dkey.configureCircuits('/circuits');
</script>

To build the browser bundle locally (e.g. after cloning the repo), run:

npm run build:browser

Quick Start

import dkey, { DkeyUserProfile, ListingMetadata } from 'dkey-lib';
import { createConfig } from '@wagmi/core';

// IMPORTANT: Copy the circuits folder from 'node_modules/dkey-lib/circuits'
// to your public/static directory, then configure the paths:
dkey.configureCircuits('/circuits'); // or './circuits' depending on your setup

// Initialize wagmi config
const config = createConfig({ /* your config */ });

// Create a user profile
const profile = new DkeyUserProfile(
  { fid: 123, fname: 'user' },
  {},
  {},
  {},
  {},
  config
);

// Create a listing
const metadata = new ListingMetadata(
  { fid: 123 },
  'example.pdf',
  'My file description',
  1024,
  0.1,
  'bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi',
  'https://example.com/cover.jpg',
  [8453], // Base chain
  1000
);

const result = await profile.createListing(
  ipfsCID,
  metadata,
  fileSecretKey,
  10, // howManyDKeysForSale
  5,  // royaltyPercentage
  address
);

Core Concepts

DkeyUserProfile

The main class for managing user interactions with the DKey protocol. Handles:

• Creating and managing listings
• Placing and managing bids
• Acquiring and managing DKeys
• Profile serialization/encryption

Listing

Represents a file listing on the blockchain. Contains:

• IPFS CID of the encrypted file
• File metadata
• Encryption keys
• Sales information

Bid

Represents a user's bid on a listing. Contains:

• Bid amount
• Public key for decryption
• Bid status

DKey

Represents an acquired decryption key. Contains:

• Encrypted file secret key
• Decryption methods
• Ownership information

API Reference

Main Exports

// Default export - utility functions
import dkey from 'dkey-lib';

// Named exports - classes and types
import {
  DkeyUserProfile,
  Listing,
  ListingMetadata,
  Bid,
  DKey,
  BidLite,
  RESULTS
} from 'dkey-lib';

Utility Functions

dkey.createKeyAndEncryptFile(data: ArrayBuffer)

Encrypts a file and generates encryption keys.

const { encryptedData, secretKeyX, secretKeyY } = 
  await dkey.createKeyAndEncryptFile(fileBuffer);

dkey.formatCID(cid: string)

Formats an IPFS CID into multiple representations.

const formatted = dkey.formatCID('bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi');
// Returns: { ipfsCIDBytes, ipfsCIDBytesString, hashedCid0xString, hashedCidString }

dkey.fetchListingDetails(ipfsCID, metadata, config)

Fetches listing details from the blockchain.

const details = await dkey.fetchListingDetails(ipfsCID, metadata, config);

dkey.configureCircuits(basePath?)

Configures circuit file paths for your environment. Call this once after importing the library.

import dkey from 'dkey-lib';

// Configure circuits to match where you serve them
dkey.configureCircuits('/public/circuits');
// or
dkey.configureCircuits('./circuits');

dkey.loadSnarkJS()

Dynamically loads the SnarkJS script in the browser environment.

await dkey.loadSnarkJS();

DkeyUserProfile Methods

createListing(...)

Creates a new file listing on the blockchain.

makeBid(...)

Places a bid on a listing.

fillBid(...)

Fills a bid (seller only).

sellDkey(...)

Sells an acquired DKey to another user.

checkIfDKeysCanBeSold(chainId)

Checks if DKeys are eligible for resale.

serialize() / deserialize()

Serialize/deserialize profile data.

toEncryptedProfileData(password) / fromEncryptedProfileData(...)

Encrypt/decrypt profile data for storage.

Supported Chains

• Base (Chain ID: 8453)
• Arbitrum (Chain ID: 42161)

Circuit Files

The library requires circuit files (.wasm, .zkey) to be accessible. By default, they're expected at:

./circuits/encryptAndHash_js/

When using this library, ensure the circuits/ folder is:

• Copied to your public/static directory, or
• Configured in your bundler to copy these assets

Then configure the paths to match your setup:

import dkey from 'dkey-lib';

// Configure circuit paths (call once after import)
dkey.configureCircuits('/public/circuits'); // or wherever you serve them

Development

# Install dependencies
npm install

# Build the library
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

TypeScript

Full TypeScript support is included. The library exports type definitions in dist/index.d.ts.

License

MIT

Contributing

Contributions are welcome - shoot Noad an email at [email protected]!

Links

• Product website
• GitHub Repository
• npm Package