SDKs

Molecule Protocol Client SDK Documentation

Overview

The @moleculexyz/client-sdk provides type-safe access to Molecule Protocol's GraphQL APIs and subgraphs, specifically for IP-NFTs, IPTokens, crowdsales, and data rooms.

Features:

• Query IPTs, markets, and IP-NFTs

• Manage data room files (upload, encrypt, retrieve)

• Interact with crowdsale data

• Handle authentication with Privy tokens

Limitations:

• Does not execute on-chain transactions. For this, use @moleculexyz/onchain + wagmi.

• Does not custody keys or manage wallets.

• Does not replace contract interactions for writes.

Supported Environments:

• Node.js 18+

• Browser (ESM)

• React/Next.js

Relationship to Contracts:

Contracts are the definitive source. This SDK queries indexed data from APIs and subgraphs for convenience. For on-chain writes, use the contract ABIs directly with viem/wagmi.

Installation

npm install @moleculexyz/client-sdk

Peer Dependencies:

npm install viem wagmi

Quickstart

This example demonstrates how to upload a file to a data room, a real write operation you can complete in under 10 minutes:

import { createDesciSdk } from '@moleculexyz/client-sdk';

// 1. Create authenticated SDK instance
const sdk = createDesciSdk({
  identityToken: 'your-privy-jwt-token',
  walletAddress: '0xYourWallet...',
});

// 2. Initiate file upload
const ipnftUid = '0xcaD88677CA87a7815728C72D74B4ff4982d54Fc1_42';
const file = new File(['Hello World'], 'readme.txt', { type: 'text/plain' });

const { uploadUrl, uploadToken } = await sdk.labs.initiateFileUploadV2(
  ipnftUid,
  file.type,
  file.size
);

// 3. Upload to signed URL
await fetch(uploadUrl, {
  method: 'PUT',
  body: file,
  headers: { 'Content-Type': file.type },
});

// 4. Finalize upload
const result = await sdk.labs.finishFileUploadV2(
  ipnftUid,
  uploadToken,
  '/documents/readme.txt',
  'PRIVATE',
  '0xYourWallet...',
  { description: 'Project readme' }
);

console.log('File uploaded:', result.path);

Prerequisites:

• Privy authentication token (from @privy-io/react-auth)

• Wallet address

• An IP-NFT you have access to

Core Abstractions

Understanding these concepts helps you use the SDK effectively:

SDK Concept	On-chain Equivalent
IPT	IPToken ERC-20 contract
IP-NFT	IP-NFT ERC-721 token
Market	Uniswap/DEX pool for an IPT
CrowdSale	CrowdSale contract instance
DataRoom	Off-chain encrypted storage tied to an IP-NFT
ProjectV2	Lab/project metadata in the API

Client

The DesciSdk client wraps all domain APIs:

const sdk = createDesciSdk(config);

Modules:

• tokens: IPT queries with market data

• ipnfts: IP-NFT queries

• labs: Data room & project management

• crowdsales: Crowdsale data from subgraph

• minting: IP-NFT minting flow

• tokenizer: IPT creation flow

Authentication Modes

Unauthenticated (public data):

• sdk.tokens.getAllWithMarkets()

• sdk.ipnfts.getById(id)

• sdk.crowdsales.getById(id)

Authenticated (requires identityToken + walletAddress):

• sdk.labs.getPassphrase(ipnftUid)

• sdk.labs.initiateFileUploadV2(...)

• sdk.minting.reserve()

Common Workflows

Display IPT Market Data

import { sdk } from '@moleculexyz/client-sdk';

// Fetch all IPTs with prices
const tokens = await sdk.tokens.getAllWithMarkets({
  sortBy: 'MARKET_CAP',
  sortOrder: 'desc',
  limit: 20,
});

// Display
tokens.forEach(token => {
  const market = token.markets[0];
  console.log(`${token.metadata.symbol}: $${market?.priceUsd || 'N/A'}`);
});

Upload Encrypted File to DataRoom (Onchain-Verified Envelope Encryption)

New uploads use Molecule's Onchain-Verified Envelope Encryption. The backend issues a one-shot plaintext DEK on initiate; the client encrypts AES-256-GCM locally and stores the wrapped DEK + access conditions on finalize. accessControlConditions is a JSON-stringified array of predicates evaluated against AccessResolver at decrypt time — see Data Privacy & Access — Worked Example for the full shape.

import { createDesciSdk } from '@moleculexyz/client-sdk';

const sdk = createDesciSdk({ identityToken, walletAddress });

// 1. Initiate with encryption: backend returns plaintext DEK + wrapped DEK + encryptionSystem
const { uploadUrl, uploadToken, plaintextDEK, encryptedDek, encryptionSystem } =
  await sdk.labs.initiateFileUploadV2(ipnftUid, 'application/octet-stream', file.size, {
    encryption: true,
  });

// 2. AES-256-GCM encrypt locally with Web Crypto, then wipe plaintextDEK
const iv = crypto.getRandomValues(new Uint8Array(12));
const key = await crypto.subtle.importKey(
  'raw', base64Decode(plaintextDEK), { name: 'AES-GCM' }, false, ['encrypt']
);
const ciphertext = await crypto.subtle.encrypt(
  { name: 'AES-GCM', iv }, key, await file.arrayBuffer()
);
// scrub plaintextDEK from memory after key import

// 3. Upload ciphertext
await fetch(uploadUrl, { method: 'PUT', body: ciphertext });

// 4. Build accessControlConditions: gate on Owner OR Contributor OR Viewer
const accessControlConditions = [
  buildIsAuthorizedSignerForTba({ accessResolver, tba }),  // covers LabNFT owner
  { operator: 'or' },
  buildHasRole({ accessResolver, oclId, role: 1 /* ROLE_VIEWER */ }), // covers Contributor + Viewer (hierarchy)
];

// 5. Finalize with encryption metadata
await sdk.labs.finishFileUploadV2(
  ipnftUid,
  uploadToken,
  '/confidential/research.pdf',
  'ADMIN',
  walletAddress,
  {
    encryptionMetadata: {
      encryptionSystem,                                       // echo from initiate
      encryptedDek,
      iv: base64Encode(iv),
      contentHash: await sha256Hex(ciphertext),
      accessControlConditions: JSON.stringify(accessControlConditions),
      encryptedBy: walletAddress,
      encryptedAt: new Date().toISOString(),
    },
  }
);

Role grants happen on-chain via the AccessResolver contract, not through this SDK. Use viem / ethers to call grantRole(oclId, account, role, expiry, isAgent) from the Lab owner; once granted, the file's hasRole condition resolves true for the grantee at decrypt time.

Upload Encrypted File (Lit Protocol, legacy)

Legacy. The flow below is retained for files encrypted before the migration to Onchain-Verified Envelope Encryption. New uploads should use the path above.

import { useLitEncryption } from '@moleculexyz/storage';

const { encryptFile } = useLitEncryption();
const encrypted = await encryptFile(file, {
  type: 'authorized_ipnft_signer',
  ipnftId: '42',
});

await sdk.labs.finishFileUploadV2(
  ipnftUid,
  uploadToken,
  '/private/research.pdf',
  'ADMIN',
  walletAddress,
  {
    encryptionMetadata: {
      dataToEncryptHash: encrypted.dataToEncryptHash,
      accessControlConditions: JSON.stringify(encrypted.accessCondition),
      chain: 'ethereum',
      litNetwork: 'datil-dev',
      // ... other Lit metadata
    },
  }
);

Check Crowdsale Contribution

const contribution = await sdk.crowdsales.getContribution(
  saleId,
  userAddress
);

if (contribution && !contribution.claimed) {
  console.log(`You can claim ${contribution.amount} tokens`);
}

Batch Read: IPTs Owned by Address

const balances = await sdk.ipnfts.getAllWithBalances(userAddress);

balances?.forEach(ipt => {
  console.log(`${ipt.symbol}: ${ipt.balance}`);
});

Transactions & Signing

Read vs Write

Operation	Type	Auth Required	On-chain
sdk.tokens.getAllWithMarkets()	Read	No	No (API)
sdk.crowdsales.getById()	Read	No	No (Subgraph)
sdk.labs.initiateFileUploadV2()	Write	Yes	No (API)
sdk.labs.finishFileUploadV2()	Write	Yes	No (API)

Who Signs What

The SDK:

• Handles API authentication (Privy JWT tokens).

• Utilizes presigned upload URLs (S3).

For on-chain transactions (minting, tokenizing, bidding), use viem/wagmi with the contract ABIs from @moleculexyz/common/abis.

Confirmation Model

SDK API calls are confirmed when the Promise resolves - these are off-chain operations. For on-chain confirmations, use wagmi's waitForTransactionReceipt.

Error Handling

Error Types

import {
  SdkError,
  AuthorizationError,
  AuthenticationRequiredError,
  NotFoundError,
  ValidationError,
  NetworkError,
  isAuthorizationError,
  isNotFoundError
} from '@moleculexyz/client-sdk';

Common Errors and Fixes

Error	Cause	Fix
AuthenticationRequiredError	Missing identityToken	Pass auth config to createDesciSdk()
AuthorizationError	No access to resource	Check wallet owns/has access to IP-NFT
NotFoundError	Invalid ID	Verify ipnftUid format: {contract}_{tokenId}
NetworkError	API unreachable	Retry with exponential backoff

Retry Guidance

import { isNetworkError } from '@moleculexyz/client-sdk';

async function fetchWithRetry(fn, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (isNetworkError(error) && i < retries - 1) {
        await new Promise(r => setTimeout(r, 1000 * (i + 1)));
        continue;
      }
      throw error;
    }
  }
}

API Reference

DesciSdk

Main client class.

class DesciSdk {
  tokens: TokensApi;
  ipnfts: IpnftsApi;
  labs: LabsApi;
  crowdsales: CrowdsalesApi;
  minting: MintingApi;
  tokenizer: TokenizerApi;

  updateAuth(auth: AuthConfig): void;
  isAuthenticated: boolean;
}

Key Methods

API	Method	Description
tokens	getAllWithMarkets()	All IPTs with market data
tokens	getById(id)	Single IPT by contract address
ipnfts	getById(uid)	IP-NFT by {contract}_{tokenId}
ipnfts	getByOwner(address)	All IP-NFTs for wallet
labs	getAll()	All projects
labs	getPassphrase(uid)	DataRoom encryption key (auth)
labs	initiateFileUploadV2()	Start file upload (auth)
labs	finishFileUploadV2()	Complete file upload (auth)
crowdsales	getById(id)	Crowdsale details
crowdsales	getContribution(saleId, user)	User's contribution

Full TypeScript types are included in the package.

Versioning & Compatibility

SemVer Policy

• Major: Breaking API changes

• Minor: New features, backward compatible

• Patch: Bug fixes

SDK ↔ Contract Compatibility

SDK Version	Contract Compatibility
0.x	IPNFT v2.5, Tokenizer v1.4, CrowdSale v1.x

The SDK queries indexed data. Contract upgrades may require SDK updates for new fields/events.

Breaking Change Policy

Breaking changes are announced in release notes with migration guides. We maintain backward compatibility for at least one minor version when possible.

Links & Resources

• Contracts: ./contracts-overview.md

• GitHub: Molecule Protocol

• NPM: Client SDK

• Changelog: See GitHub releases

• Related SDKs:

  • ./onchain.md — Wallet integration.

  • ./storage.md — File encryption.

  • ./core.md — Utilities & schemas

• Support: Discord