ParaloomPARALOOM

API Reference

Developer API documentation for Paraloom

API Reference

This document covers the core APIs for interacting with Paraloom.

Privacy API

Create Commitment

Generate a commitment for a deposit:

use paraloom::privacy::poseidon::poseidon_hash_pair;

/// Create a commitment from value and randomness
pub fn create_commitment(value: u64, randomness: &[u8; 32]) -> [u8; 32] {
    let value_bytes = value.to_le_bytes();
    let mut input = [0u8; 32];
    input[..8].copy_from_slice(&value_bytes);

    poseidon_hash_pair(&input, randomness)
}

Create Nullifier

Generate a nullifier from commitment and secret:

/// Create a nullifier to spend a commitment
pub fn create_nullifier(commitment: &[u8; 32], secret: &[u8; 32]) -> [u8; 32] {
    poseidon_hash_pair(commitment, secret)
}

Generate Withdrawal Proof

use paraloom::privacy::circuits::WithdrawalCircuit;

pub struct WithdrawalProofInput {
    // Public inputs
    pub nullifier: [u8; 32],
    pub amount: u64,
    pub recipient: [u8; 32],
    pub merkle_root: [u8; 32],

    // Private inputs (hidden)
    pub value: u64,
    pub randomness: [u8; 32],
    pub secret: [u8; 32],
    pub merkle_path: Vec<[u8; 32]>,
}

/// Generate zkSNARK proof for withdrawal
pub fn generate_proof(input: WithdrawalProofInput) -> Result<Vec<u8>, Error> {
    let circuit = WithdrawalCircuit::new(input);
    let proof = Groth16::<Bls12_381>::prove(&PROVING_KEY, circuit, &mut rng)?;
    Ok(proof.to_bytes())
}

Compute API

Submit Job

use paraloom::compute::{Job, JobConfig};

pub struct Job {
    pub wasm_code: Vec<u8>,
    pub input: Vec<u8>,
    pub config: JobConfig,
}

pub struct JobConfig {
    pub memory_limit: usize,      // Default: 64MB
    pub instruction_limit: u64,   // Default: 1B (1,000,000,000)
    pub timeout_secs: u64,        // Default: 30s (max: 300s)
    pub private: bool,            // Enable privacy
}

/// Submit a compute job
pub async fn submit_job(job: Job) -> Result<JobId, Error> {
    let network = NetworkClient::connect().await?;
    let job_id = network.submit_job(job).await?;
    Ok(job_id)
}

Private Job Submission

use paraloom::compute::PrivateJob;

pub struct PrivateJob {
    pub wasm_code: Vec<u8>,
    pub encrypted_input: Vec<u8>,
    pub input_commitment: [u8; 32],
    pub config: JobConfig,
}

/// Submit a privacy-preserving compute job
pub async fn submit_private_job(job: PrivateJob) -> Result<JobId, Error> {
    let network = NetworkClient::connect().await?;

    // Job input is encrypted, only output commitment is public
    let job_id = network.submit_private_job(job).await?;

    Ok(job_id)
}

Get Job Result

pub struct JobResult {
    pub job_id: JobId,
    pub status: JobStatus,
    pub output: Option<Vec<u8>>,
    pub execution_time_ms: u64,
    pub validators: Vec<NodeId>,
}

pub enum JobStatus {
    Pending,
    Running,
    Completed,
    Failed(String),
}

/// Get result of a compute job
pub async fn get_result(job_id: JobId) -> Result<JobResult, Error> {
    let network = NetworkClient::connect().await?;
    let result = network.get_job_result(job_id).await?;
    Ok(result)
}

Bridge API

Deposit

use paraloom::bridge::BridgeClient;

pub struct DepositParams {
    pub amount: u64,           // In lamports
    pub commitment: [u8; 32],  // Hash of amount + randomness
}

/// Deposit SOL into privacy pool
pub async fn deposit(params: DepositParams) -> Result<Signature, Error> {
    let client = BridgeClient::new(rpc_url, program_id)?;
    let sig = client.deposit(params.amount, params.commitment).await?;
    Ok(sig)
}

Withdraw

pub struct WithdrawParams {
    pub proof: Vec<u8>,        // zkSNARK proof
    pub nullifier: [u8; 32],   // Prevents double-spend
    pub amount: u64,           // In lamports
    pub recipient: Pubkey,     // SOL address
}

/// Withdraw SOL from privacy pool
pub async fn withdraw(params: WithdrawParams) -> Result<Signature, Error> {
    let client = BridgeClient::new(rpc_url, program_id)?;

    // First, submit to consensus network
    let consensus = ConsensusClient::connect().await?;
    let approved = consensus.verify_withdrawal(&params).await?;

    if !approved {
        return Err(Error::ConsensusRejected);
    }

    // Then submit on-chain
    let sig = client.withdraw(params).await?;
    Ok(sig)
}

Network API

Connect to Network

use paraloom::network::NetworkClient;

pub struct NetworkConfig {
    pub bootstrap_peers: Vec<Multiaddr>,
    pub listen_addr: Multiaddr,
    pub enable_mdns: bool,
}

/// Connect to Paraloom P2P network
pub async fn connect(config: NetworkConfig) -> Result<NetworkClient, Error> {
    let client = NetworkClient::new(config).await?;
    client.start_discovery().await?;
    Ok(client)
}

Validator Registration

pub struct ValidatorInfo {
    pub node_id: NodeId,
    pub stake: u64,
    pub capacity: ResourceCapacity,
}

/// Register as a validator
pub async fn register_validator(info: ValidatorInfo) -> Result<(), Error> {
    let network = NetworkClient::connect().await?;
    network.register_validator(info).await?;
    Ok(())
}

Consensus API

Submit Verification Request

pub struct VerificationRequest {
    pub request_id: String,
    pub proof: Vec<u8>,
    pub public_inputs: PublicInputs,
}

/// Submit proof for consensus verification
pub async fn submit_verification(req: VerificationRequest) -> Result<ConsensusResult, Error> {
    let consensus = ConsensusClient::connect().await?;
    let result = consensus.submit_and_wait(req).await?;
    Ok(result)
}

Error Codes

CodeDescription
E001Invalid proof
E002Nullifier already spent
E003Merkle root mismatch
E004Insufficient stake
E005Consensus timeout
E006Job execution failed
E007Network connection failed
E008Invalid commitment

Rate Limits

EndpointLimit
Deposits100/hour per address
Withdrawals50/hour per address
Compute jobs100/hour per address
API queries1000/minute

WebSocket Events

// Subscribe to events
ws.subscribe('deposits', (event) => {
  console.log('New deposit:', event.commitment);
});

ws.subscribe('withdrawals', (event) => {
  console.log('Withdrawal:', event.nullifier);
});

ws.subscribe('compute_jobs', (event) => {
  console.log('Job completed:', event.job_id);
});

On this page