Skip to main content

SDK Quickstart

This page shows how to integrate ZEclipse from a DApp or backend using the TypeScript SDK and connectors described in README.md, DOCUMENTATION.md, and docs/TECHNICAL_DOCUMENTATION.md.

Installing the SDK​

From the BlackoutSOL/app package (or your published SDK package name):

npm install @zeclipsesol/sdk

Basic Private Transfer​

The TimingEnhancedConnector wraps the core connector with temporal obfuscation:

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,      // Number of real splits per hop
  fakeSplitsPerHop: 44,    // Additional fake splits for anonymity
  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`)

Using the DApp Connector​

For web or backend apps, the DApp connector provides a simpler API (docs/CONNECTOR_GUIDE.md and docs/TECHNICAL_DOCUMENTATION.md):

import {
  BlackoutDAppConnector,
  DAppConfig,
  TransferRequest,
} from '@blackoutsol/connector'

const config: DAppConfig = {
  rpcUrl: 'https://api.mainnet-beta.solana.com',
  commitment: 'confirmed',
  useDevnet: false,
}

const connector = new BlackoutDAppConnector(config)
await connector.initialize()

const request: TransferRequest = {
  amount: 1_500_000_000, // 1.5 SOL
  recipients: [
    'GsbwXfJraMomkTbU3KjALchLz1UyjjSJcST5zrTQ1Do9',
    'HXk3B5mGNHXDKU9F6RLuNVzUGCc1YP4uwupcFMUe3Qid',
  ],
  showEfficiency: true,
  payerKeypair, // obtain from a secure wallet integration
}

const response = await connector.executeTransfer(request)

if (response.success) {
  console.log(`Transfer successful: ${response.signature}`)
  if (response.efficiency) {
    console.log(`Efficiency: ${response.efficiency.efficiency}%`)
  }
} else {
  console.error(`Transfer failed: ${response.error}`)
}

Efficiency Metrics​

You can pre-compute efficiency metrics for UI display:

const efficiency = connector.calculateTransferEfficiency(
  1_500_000_000, // amount in lamports
  2,             // number of recipients
)

console.log(`Transfer efficiency: ${efficiency.efficiency}%`)
console.log(`Cost breakdown: ${JSON.stringify(efficiency.costBreakdown)}`)

See Core Concepts → Cost Efficiency for the underlying model and benchmark numbers.