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(¶ms).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
| Code | Description |
|---|---|
E001 | Invalid proof |
E002 | Nullifier already spent |
E003 | Merkle root mismatch |
E004 | Insufficient stake |
E005 | Consensus timeout |
E006 | Job execution failed |
E007 | Network connection failed |
E008 | Invalid commitment |
Rate Limits
| Endpoint | Limit |
|---|---|
| Deposits | 100/hour per address |
| Withdrawals | 50/hour per address |
| Compute jobs | 100/hour per address |
| API queries | 1000/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);
});