✍️Documentation

ZK Void Confidential Transfer API

🔐 Privacy-First Token Transfers on Solana

The ZK Void Confidential Transfer API enables developers to integrate confidential token transfers into their dApps using Solana's SPL Token 2022 confidential transfer extensions. Our trusted backend model handles complex zero-knowledge proof generation while users maintain full control of their wallets.

🌟 Features

  • Confidential Transfers: Hide transaction amounts using zero-knowledge proofs

  • Easy Integration: Simple REST API with comprehensive documentation

  • Wallet Control: Users sign their own transactions and pay their own fees

  • Multi-Token Support: Works with any SPL Token 2022 mint with confidential extensions

  • Production Ready: Checkhttps://api.zkvoid.com/health for status

  • 🛡️ Security First: Deterministic key derivation with no private key storage

🚀 Quick Start

1. Basic Setup

const API_BASE_URL = 'https://api.zkvoid.com';

// Helper function to call the API
async function callAPI(endpoint: string, data: any) {
  const response = await fetch(`${API_BASE_URL}${endpoint}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  });

  const result = await response.json();
  if (!result.success) {
    throw new Error(result.error);
  }
  
  return result.data;
}

2. Setup Confidential Account

// Generate signature for key derivation
const message = `Confidential Transfer Key Derivation: ${wallet.publicKey.toString()}`;
const signature = await wallet.signMessage(new TextEncoder().encode(message));
const signatureBase64 = Buffer.from(signature).toString('base64');

// Setup account
const response = await callAPI('/setup-account', {
  owner_pubkey: wallet.publicKey.toString(),
  signature: signatureBase64,
  mint_address: 'your_token_mint_address',
});

// Sign and submit the transaction
const transaction = Transaction.from(Buffer.from(response.transaction, 'base64'));
const signedTx = await wallet.signTransaction(transaction);
const txSignature = await connection.sendRawTransaction(signedTx.serialize());

3. Check Balance

const balance = await callAPI('/balance', {
  owner_pubkey: wallet.publicKey.toString(),
  signature: signatureBase64,
  mint_address: 'your_token_mint_address',
});

console.log('Available:', balance.available_balance);
console.log('Pending:', balance.pending_balance);
console.log('Public:', balance.public_balance);

4. Confidential Transfer

const transferResponse = await callAPI('/transfer', {
  sender_pubkey: wallet.publicKey.toString(),
  sender_signature: signatureBase64,
  recipient_pubkey: 'recipient_wallet_address',
  amount: 1000000, // Amount in smallest token units
  mint_address: 'your_token_mint_address',
});

// Execute multiple transactions sequentially
for (let i = 0; i < transferResponse.transactions.length; i++) {
  const transaction = Transaction.from(Buffer.from(transferResponse.transactions[i], 'base64'));
  
  // Handle additional signers if present
  if (transferResponse.additional_signers?.[i]) {
    // Add additional signers to transaction
  }
  
  const signedTx = await wallet.signTransaction(transaction);
  const signature = await connection.sendRawTransaction(signedTx.serialize());
  await connection.confirmTransaction(signature);
}

📚 Documentation

📖 Complete Guides

  • API Documentation - Complete API reference with all endpoints, request/response formats, and error codes

  • Integration Cookbook - Practical examples, patterns, and real-world use cases

🔗 Quick Links

  • Base URL: https://api.zkvoid.com

  • Health Check: GET /health

  • Rate Limits: 100 requests/minute (general), 10 requests/minute (transfers)

  • Support: x | [email protected]

🛠️ API Endpoints

Endpoint
Method
Description

/health

GET

Service health check

/setup-account

POST

Setup confidential token account

/deposit

POST

Convert regular tokens to confidential

/apply-pending-balance

POST

Apply pending balance

/balance

POST

Get confidential balance

/transfer

POST

Execute confidential transfer

/withdraw

POST

Convert confidential tokens back to regular

🎯 Use Cases

💰 Private Payments

Enable private transactions between users without revealing amounts on-chain.

const paymentSystem = new PrivatePaymentSystem('your_mint_address');
const { signatures } = await paymentSystem.sendPrivatePayment(
  senderWallet,
  recipientAddress,
  amount
);

🗳️ Anonymous Voting

Create voting systems where vote amounts remain private.

const voting = new AnonymousVoting('voting_mint', 'voting_authority');
const { voteId } = await voting.castVote(voterWallet, pollId, optionId, voteWeight);

🤝 Confidential Escrow

Build escrow services with private transaction amounts.

const escrow = new ConfidentialEscrow({ mintAddress, escrowDuration: 3600 });
const { escrowId } = await escrow.createEscrow(buyerWallet, sellerAddress, amount);

💼 Private DeFi

Integrate into DeFi protocols for private trading and lending.

🔐 Security Model

Key Derivation

  • Deterministic: Same wallet always generates same encryption keys

  • Message-Based: Uses standardized message format for consistency

  • No Storage: Private keys never leave the client or get stored

Transaction Security

  • Client-Side Signing: Users sign all transactions with their wallet

  • Zero-Knowledge Proofs: Transaction amounts hidden using ZK proofs

  • Audit Trail: All transactions verifiable on-chain

Network Security

  • HTTPS Only: All API communications encrypted

  • CORS Configured: Proper cross-origin resource sharing

  • Rate Limited: Protection against abuse and DDoS

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Your dApp     │    │   ZK Void API   │    │  Solana Network │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │   Wallet    │ │    │ │ Proof Gen   │ │    │ │ Token 2022  │ │
│ │ Integration │◄┼────┼►│   Service   │ │    │ │  Program    │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ Transaction │ │    │ │ Key Derive  │ │    │ │ Confidential│ │
│ │  Handling   │ │    │ │   Service   │ │    │ │ Extensions  │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🚦 Getting Started

Prerequisites

  1. SPL Token 2022 Mint with confidential transfer extension

  2. Solana Wallet with message signing support (Phantom, Solflare, etc.)

  3. RPC Connection to Solana mainnet/devnet

Integration Steps

  1. Setup Account: Enable confidential transfers for your token

  2. Deposit Tokens: Convert regular tokens to confidential state

  3. Apply Pending: Make deposited tokens available for transfers

  4. Transfer: Execute private transfers between wallets

  5. Withdraw: Convert back to regular tokens when needed

Example Integration

import { useWallet } from '@solana/wallet-adapter-react';
import { ConfidentialTransferClient } from './confidential-client';

function MyDApp() {
  const wallet = useWallet();
  const client = new ConfidentialTransferClient();

  const handlePrivateTransfer = async () => {
    try {
      // Setup if needed
      await client.setupAccount(wallet, mintAddress);
      
      // Check balance
      const balance = await client.getBalance(wallet, mintAddress);
      
      // Execute transfer
      const signatures = await client.transfer(
        wallet, 
        recipientAddress, 
        amount, 
        mintAddress
      );
      
      console.log('Transfer completed:', signatures);
    } catch (error) {
      console.error('Transfer failed:', error);
    }
  };

  return (
    <div>
      <button onClick={handlePrivateTransfer}>
        Send Private Payment
      </button>
    </div>
  );
}

📊 Supported Tokens

The API works with any SPL Token 2022 mint that has the confidential transfer extension enabled. Popular tokens include:

  • PYUSD (when auditor allows approval)

  • Custom Tokens with confidential extensions

  • DAO Tokens for private governance

  • Gaming Tokens for private in-game transactions

🔧 Development Tools

Testing

# Health check
curl https://api.zkvoid.com/health

# Mock responses for testing
const mockClient = new MockConfidentialClient();
mockClient.setMockResponse('/balance', { available_balance: 1000 });

Monitoring

// Track API usage
analytics.track('confidential_transfer_initiated', {
  amount: amount,
  mintAddress: mintAddress,
});

Error Handling

try {
  await client.transfer(wallet, recipient, amount, mint);
} catch (error) {
  if (error.message.includes('Account not found')) {
    // Setup account first
    await client.setupAccount(wallet, mint);
  } else if (error.message.includes('Insufficient balance')) {
    // Handle insufficient funds
  }
}

🌍 Deployment

Production

  • URL: https://api.zkvoid.com

  • Status: ✅ Live

  • Rate Limits: Enforced

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Solana Labs for SPL Token 2022 and confidential transfer extensions

  • Anza for the Agave validator and tooling

  • Community for feedback and contributions

Built with ❤️ for the Solana ecosystem

Making confidential transfers accessible to every dApp developer

PreviouscSOLNextCookbook

Last updated