Skip to main content

DApp Connector

The ZEclipse DApp Connector is the recommended integration surface for web frontends and backends.

It wraps the underlying SDK and protocol details into a small, typed API, as described in docs/CONNECTOR_GUIDE.md and docs/TECHNICAL_DOCUMENTATION.md.

When to Use​

Use the DApp connector when:

  • You are building a DApp or backend that should trigger private transfers.
  • You want cost efficiency metrics and standardized error handling.
  • You don’t need to manage low-level transactions yourself.

If you need more control (e.g., temporal tuning, custom routing), see Developer Guides → SDK Integration.

Installation​

From your app:

npm install @blackoutsol/connector

Initializing the Connector​

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

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

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

Executing an Anonymous Transfer​

import { TransferRequest } from '@blackoutsol/connector'

// Obtain from a secure wallet integration
const payerKeypair = wallet.getKeypair()

const request: TransferRequest = {
  amount: 1_500_000_000, // 1.5 SOL in lamports
  recipients: [
    'GsbwXfJraMomkTbU3KjALchLz1UyjjSJcST5zrTQ1Do9',
    'HXk3B5mGNHXDKU9F6RLuNVzUGCc1YP4uwupcFMUe3Qid',
  ],
  showEfficiency: true,
  payerKeypair,
}

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}`)
}

Cost Efficiency API​

You can pre-compute efficiency numbers for UI display, using the connector’s efficiency helpers:

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

console.log(`Transfer efficiency: ${efficiency.efficiency}%`)
console.log(`Total cost: ${efficiency.totalCost} lamports`)
console.log(`Savings vs baseline: ${efficiency.savingsVsBaseline} lamports`)

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

Error Handling​

The connector exposes error codes so you can branch on specific failure modes:

import { BlackoutErrorCode } from '@blackoutsol/connector'

if (response.error?.includes(BlackoutErrorCode.INSUFFICIENT_FUNDS)) {
  showNotification("Your wallet doesn't have enough SOL for this transfer")
} else if (response.error?.includes(BlackoutErrorCode.INVALID_RECIPIENT)) {
  showNotification("One or more recipient addresses are invalid")
}

Common categories:

  • INSUFFICIENT_FUNDS
  • INVALID_RECIPIENT
  • Network / RPC connectivity errors
  • Internal program errors (e.g., proof verification failure)

Production Readiness Notes​

From the connector documentation:

  • Core functionality is implemented and tested (multi-wallet, efficiency metrics, basic error handling).
  • Integration and stress testing still need expansion.
  • Cryptographic and ZK components require independent security review.

Treat ZEclipse as beta: suitable for demos, experimentation, and controlled pilots, but not yet a fully-audited privacy infrastructure.