Skip to main content

SDK Integration

This page covers using the TypeScript SDK directly for applications that need:

  • Fine-grained control over temporal obfuscation.
  • Access to low-level APIs (e.g., proof generation hooks, custom routing logic).
  • Integration with existing Solana tooling.

It summarizes patterns from DOCUMENTATION.md, docs/TECHNICAL_DOCUMENTATION.md, and the SDK source under app/src.

Installing the SDK​

From your project:

npm install @zeclipsesol/sdk

In the monorepo, the SDK lives under BlackoutSOL/app. When publishing, use your chosen package name and versioning.

Timing-Enhanced Connector​

The most common entry point is the TimingEnhancedConnector, which combines:

  • Core private transfer logic.
  • Temporal obfuscation (TimeObfuscator, TemporalObfuscationManager).
import { TimingEnhancedConnector } from '@zeclipsesol/sdk'

const connector = new TimingEnhancedConnector({
  rpcUrl: 'https://api.mainnet-beta.solana.com',
  maxHops: 4,           // recommended minimum for strong privacy
  maxSplitsPerHop: 4,   // real splits per hop
  fakeSplitsPerHop: 44, // fake splits per hop
  privacyLevel: 'MAXIMUM_PRIVACY',
  temporalStrategy: 'ADAPTIVE',
})

const result = await connector.executePrivateTransfer({
  sender: senderKeypair,
  recipient: recipientPublicKey,
  amount: 1_000_000_000, // 1 SOL in lamports
})

const privacyStats = connector.getPrivacyStats()
console.log(`Effective anonymity set: ${privacyStats.anonymitySetSize}`)
console.log(`Temporal entropy score: ${privacyStats.entropyScore}/100`)

Temporal Obfuscation Controls​

If you need direct timing control, you can work with the underlying temporal APIs:

import {
  TimeObfuscator,
  TimingStrategy,
  TemporalObfuscationConfig,
} from '@zeclipsesol/sdk'

const obfuscator = new TimeObfuscator(connection)

// Use a custom config instead of a preset strategy
const config: TemporalObfuscationConfig = {
  minDelay: 1000,
  maxDelay: 8000,
  randomBatchOrder: true,
  timeSlicedExecution: true,
  timeWindowSize: 60000,
  timeSliceInterval: 2000,
}

obfuscator.setConfig(config)

For most apps, the preset strategies via TimingStrategy and TimingEnhancedConnector are sufficient.

See Core Concepts → Temporal Obfuscation for strategy details.

Multi-Recipient Transfers​

ZEclipse supports splitting a transfer across multiple recipients (typically 3–6) while:

  • Maintaining a single underlying transfer state.
  • Sharing ZK proof overhead and compute costs.

Example (conceptually aligned with docs/TECHNICAL_DOCUMENTATION.md):

const response = await connector.executePrivateTransfer({
  sender: senderKeypair,
  recipients: [
    recipientA,
    recipientB,
    recipientC,
  ],
  amount: 3_000_000_000, // 3 SOL total in lamports
})

On-chain, recipients are stored in a fixed-size array with a recipient_count field; the SDK takes care of encoding this structure.

Accessing Low-Level Clients​

Below the connectors, the SDK exposes:

  • A Blackout client that talks directly to the Anchor program.
  • Helpers for proof generation and verification orchestration.
  • Utilities for efficiency analysis and terminal dashboards.

If you need to:

  • Plug into a custom proof system.
  • Swap in a different timing backend.
  • Integrate into an existing job/queue system.

…you can bypass the high-level connectors and call these lower-level modules directly. See the app/src/client, app/src/connector, and app/src/efficiency folders for reference implementations.

Security & Audit Caveats​

From the core docs:

  • ZK components (HyperPlonk, range proofs, Merkle verification) are not yet production-audited.
  • Poseidon hashing and parameter choices are critical for soundness.
  • Treat the SDK as beta and avoid high-stakes production use until formal audits are complete.

Always pair SDK usage with:

  • Rigorous input validation.
  • Wallet best practices (no private keys in frontends).
  • Clear communication to end users about current security status.