CIFER SDK - Quantum-Resistant Blockchain Encryption

> Skill for AI Agents | Enable quantum-resistant encryption in blockchain applications using the CIFER SDK.

Overview

CIFER (Cryptographic Infrastructure for Encrypted Records) SDK provides quantum-resistant encryption for blockchain applications. This skill enables AI agents to implement secure data encryption, secret management, and on-chain commitments using post-quantum cryptography.

Key Capabilities

• Quantum-Resistant Encryption: ML-KEM-768 (NIST standardized) key encapsulation
• Multi-Chain Support: Automatic chain discovery and configuration
• Wallet Agnostic: Works with MetaMask, WalletConnect, Coinbase, Thirdweb, and custom signers
• File Encryption: Async job system for large file encryption/decryption
• On-Chain Commitments: Store encrypted data references on-chain with log-based retrieval
• Transaction Intents: Non-custodial pattern - you control transaction execution

When to Use This Skill

Use the CIFER SDK when you need to:

• Encrypt sensitive data with quantum-resistant algorithms
• Store encrypted records on blockchain
• Manage encryption keys with owner/delegate authorization
• Encrypt files larger than 16KB using the job system
• Build applications requiring post-quantum security

Installation

npm install cifer-sdk
# or
yarn add cifer-sdk
# or
pnpm add cifer-sdk

Requirements: Node.js 18.0+, TypeScript 5.0+ (recommended)

Quick Start

import { createCiferSdk, Eip1193SignerAdapter, blackbox } from 'cifer-sdk';

// 1. Initialize SDK with auto-discovery
const sdk = await createCiferSdk({
  blackboxUrl: 'https://blackbox.cifer.network',
});

// 2. Connect wallet (browser)
const signer = new Eip1193SignerAdapter(window.ethereum);

// 3. Encrypt data
const encrypted = await blackbox.payload.encryptPayload({
  chainId: 752025,
  secretId: 123n,
  plaintext: 'My secret message',
  signer,
  readClient: sdk.readClient,
  blackboxUrl: sdk.blackboxUrl,
});

// 4. Decrypt data
const decrypted = await blackbox.payload.decryptPayload({
  chainId: 752025,
  secretId: 123n,
  encryptedMessage: encrypted.encryptedMessage,
  cifer: encrypted.cifer,
  signer,
  readClient: sdk.readClient,
  blackboxUrl: sdk.blackboxUrl,
});

console.log(decrypted.decryptedMessage); // 'My secret message'

---

Core Concepts

Secrets

A secret is the core primitive in CIFER. Each secret represents an ML-KEM-768 key pair:

| Property | Description | |----------|-------------| | owner | Address that can transfer, set delegate, and decrypt | | delegate | Address that can decrypt only (zero address if none) | | isSyncing | true while key generation is in progress | | clusterId | Which enclave cluster holds the private key shards | | secretType | 1 = ML-KEM-768 (standard) | | publicKeyCid | IPFS CID of public key (empty if syncing) |

Lifecycle: Creation → Syncing (~30-60s) → Ready

Authorization Model

| Role | Capabilities | |------|-------------| | Owner | Encrypt, decrypt, transfer, set delegate | | Delegate | Decrypt only |

Encryption Model

CIFER uses hybrid encryption:

1. ML-KEM-768: Post-quantum key encapsulation (1088-byte ciphertext)
2. AES-256-GCM: Symmetric encryption for actual data

Output format:

• cifer: 1104 bytes (ML-KEM ciphertext + tag)
• encryptedMessage: Variable length (max 16KB)

Transaction Intents

The SDK returns transaction intents instead of executing transactions:

interface TxIntent {
  chainId: number;
  to: Address;
  data: Hex;
  value?: bigint;
}

Execute with any wallet library (ethers, wagmi, viem).

---

API Reference

SDK Initialization

With Discovery (Recommended)

const sdk = await createCiferSdk({
  blackboxUrl: 'https://blackbox.cifer.network',
});

sdk.getSupportedChainIds(); // [752025, 11155111, ...]
sdk.getControllerAddress(752025); // '0x...'
sdk.getRpcUrl(752025); // 'https://...'

With Overrides

const sdk = await createCiferSdk({
  blackboxUrl: 'https://blackbox.cifer.network',
  chainOverrides: {
    752025: {
      rpcUrl: 'https://my-private-rpc.example.com',
      secretsControllerAddress: '0x...',
    },
  },
});

Synchronous (No Discovery)

import { createCiferSdkSync, RpcReadClient } from 'cifer-sdk';

const readClient = new RpcReadClient({
  rpcUrlByChainId: {
    752025: 'https://mainnet.ternoa.network',
  },
});

const sdk = createCiferSdkSync({
  blackboxUrl: 'https://blackbox.cifer.network',
  readClient,
  chainOverrides: {
    752025: {
      rpcUrl: 'https://mainnet.ternoa.network',
      secretsControllerAddress: '0x...',
    },
  },
});

---

Wallet Integration

All wallets must implement the SignerAdapter interface:

interface SignerAdapter {
  getAddress(): Promise<string>;
  signMessage(message: string): Promise<string>;
  sendTransaction?(txRequest: TxIntent): Promise<TxExecutionResult>;
}

MetaMask

import { Eip1193SignerAdapter } from 'cifer-sdk';

await window.ethereum.request({ method: 'eth_requestAccounts' });
const signer = new Eip1193SignerAdapter(window.ethereum);

WalletConnect v2

import { EthereumProvider } from '@walletconnect/ethereum-provider';

const provider = await EthereumProvider.init({
  projectId: 'YOUR_WALLETCONNECT_PROJECT_ID',
  chains: [752025],
  showQrModal: true,
});

await provider.connect();
const signer = new Eip1193SignerAdapter(provider);

Private Key (Server-Side)

import { Wallet } from 'ethers';

const wallet = new Wallet(process.env.PRIVATE_KEY);

const signer = {
  async getAddress() { return wallet.address; },
  async signMessage(message) { return wallet.signMessage(message); },
};

wagmi (React)

import { useAccount, useConnectorClient } from 'wagmi';

function useCiferSigner() {
  const { address, isConnected } = useAccount();
  const { data: connectorClient } = useConnectorClient();

  const getSigner = async () => {
    if (!isConnected || !connectorClient) {
      throw new Error('Wallet not connected');
    }
    const provider = await connectorClient.transport;
    return new Eip1193SignerAdapter(provider);
  };

  return { getSigner, address, isConnected };
}

---

keyManagement Namespace

Interact with the SecretsController contract for secret management.

Read Operations

// Get secret creation fee
const fee = await keyManagement.getSecretCreationFee({
  chainId: 752025,
  controllerAddress: sdk.getControllerAddress(752025),
  readClient: sdk.readClient,
});

// Get secret state
const state = await keyManagement.getSecret(params, 123n);
// Returns: { owner, delegate, isSyncing, clusterId, secretType, publicKeyCid }

// Check if secret is ready
const ready = await keyManagement.isSecretReady(params, 123n);

// Check authorization
const canDecrypt = await keyManagement.isAuthorized(params, 123n, '0x...');

// Get secrets by wallet
const secrets = await keyManagement.getSecretsByWallet(params, '0xUser...');
// Returns: { owned: bigint[], delegated: bigint[] }

Transaction Builders

// Create a new secret
const fee = await keyManagement.getSecretCreationFee(params);
const txIntent = keyManagement.buildCreateSecretTx({
  chainId: 752025,
  controllerAddress: sdk.getControllerAddress(752025),
  fee,
});

// Set delegate
const txIntent = keyManagement.buildSetDelegateTx({
  chainId: 752025,
  controllerAddress: sdk.getControllerAddress(752025),
  secretId: 123n,
  newDelegate: '0xDelegate...',
});

// Remove delegate
const txIntent = keyManagement.buildRemoveDelegationTx({ ... });

// Transfer ownership (irreversible!)
const txIntent = keyManagement.buildTransferSecretTx({
  chainId: 752025,
  controllerAddress: sdk.getControllerAddress(752025),
  secretId: 123n,
  newOwner: '0xNewOwner...',
});

...