Privacy API Reference

The dregg_sdk::privacy module provides ergonomic wrappers around dregg's privacy primitives. Each method documents what the verifier learns and what stays hidden.

Privacy Stack Summary

What	How	Status
Credential privacy	BlindedMerklePoseidon2StarkAir (ZK auth, unlinkable multi-show)	Working
Amount privacy	Pedersen commitments + Bulletproof range proofs	Working
Recipient privacy	Stealth addresses (per-transaction derived keys)	Working
Intent privacy	SSE encrypted headers + delay pool	Working
Network privacy	Dandelion++ origin hiding + message padding	Working
Transaction privacy	Committed conservation in executor	Working

Honest limitations: Intent CONTENT is partially visible -- SSE keyword tokens are enumerable by knowledgeable observers who know the keyword space. The executor sees sovereign state during mediated (non-peer-to-peer) interactions. Use peer_exchange_session() for maximum privacy between known parties.

Anonymous Authorization

Prove you are authorized without revealing which federation member you are.

pub fn authorize_anonymously(&self, token: &HeldToken, request: &AuthRequest) -> Result<AnonymousPresentation, SdkError>

Verifier learns: Some valid federation member authorized this request + a unique presentation tag.
Hidden: Which member, token contents, delegation chain, all prior proofs (unlinkable).
Mechanism: BlindedMerklePoseidon2StarkAir with fresh per-presentation blinding.

use dregg_sdk::{AgentCipherclerk, AuthRequest};

let mut cclerk = AgentCipherclerk::new();
let token = cclerk.mint_token(b"secret-key-32-bytes-here!!!!!!!!!", "service");

let request = AuthRequest {
    service: Some("service".into()),
    action: Some("read".into()),
    ..Default::default()
};

let presentation = cclerk.authorize_anonymously(&token, &request).unwrap();
// presentation.presentation_tag is unique and unlinkable per call

Private Notes (Hidden Balances)

Create and transfer value without revealing amounts.

pub fn create_private_note(&self, value: u64, asset_type: u64) -> Result<(NoteCommitment, NoteSecret), SdkError>

pub fn transfer_note_privately(&self, note_secret: &NoteSecret, recipient_key: &[u8; 32], merkle_siblings: Vec<[BabyBear; 3]>, merkle_positions: Vec<u8>) -> Result<NoteTransferProof, SdkError>

Verifier learns: A nullifier (double-spend prevention), a Merkle root (note exists), a new commitment (goes to recipient).
Hidden: Value, asset type, spending key, sender identity, recipient identity, which note was spent.

Unlinkable Predicate Proofs

Prove facts about yourself that cannot be correlated across sessions.

pub fn prove_predicate_unlinkable(&self, token: &HeldToken, attribute: &str, attribute_value: u32, predicate_type: PredicateType, threshold: BabyBear) -> Result<UnlinkablePredicateProof, SdkError>

Verifier learns: The predicate is satisfied (e.g., "balance >= 1000") + a blinded fact commitment (unique per proof).
Hidden: The actual value, which token, which identity, any correlation with other proofs.
Mechanism: Fresh random BabyBear blinding generates a new Poseidon2(fact_hash, state_root, blinding, 0) each time.

Non-Revocation Proofs

Prove your token has not been revoked without revealing which token you hold.

pub fn prove_not_revoked(&self, token: &HeldToken, revocation_tree: &SortedRevocationTree) -> Result<NonRevocationProof, SdkError>

Verifier learns: The prover holds a non-revoked capability + the revocation set root.
Hidden: Which capability, derivation chain, which ancestors were checked.
Mechanism: NonRevocationAir -- sorted-Merkle non-membership proof for all ancestors simultaneously.

Private Intent Discovery

pub async fn discover_intents_privately(&self, tag: &str, node_a_url: &str, node_b_url: &str, transport: T) -> Result<Vec<[u8; 32]>, SdkError>

Each server learns: That someone is querying. Nothing else.
Hidden: Which tag was searched for, which row was accessed.
Security model: Information-theoretic (not computational) -- non-collusion assumption.

Stealth Addresses (Recipient Privacy)

Generate one-time receive addresses so senders cannot be linked to recipients.

pub fn stealth_meta_address(&self) -> StealthAddress

pub fn private_transfer(&mut self, amount: u64, recipient: &StealthAddress) -> Result<PrivateTransferProof, SdkError>

Verifier learns: A nullifier, a new note commitment, a conservation proof (amounts balance).
Hidden: Transfer amount, sender identity, recipient identity, which note was spent.
Mechanism: Pedersen commitment to amount + Bulletproof range proof + stealth address derivation.

use dregg_sdk::AgentCipherclerk;

let mut alice = AgentCipherclerk::new();
let mut bob = AgentCipherclerk::new();

// Bob publishes his stealth meta-address (share publicly or via discovery)
let bob_stealth = bob.stealth_meta_address();

// Alice sends privately -- federation never sees the amount or recipient
let proof = alice.private_transfer(500, &bob_stealth).unwrap();

// Bob scans for incoming notes using his viewing key
let incoming = bob.scan_for_notes(&note_tree).unwrap();

Peer-to-Peer Exchange (No Federation)

For maximum privacy, interact directly with a known peer. The federation is never contacted.

pub fn peer_exchange_session(&mut self, peer: &PublicKey) -> Result<PeerSession, SdkError>

Network learns: Nothing (direct connection between peers).
Federation learns: Nothing (not contacted).
Peer learns: Your new state commitment + proof of valid transition.

Verification Helpers

use dregg_sdk::{
    verify_anonymous_presentation,
    verify_non_revocation_proof,
    verify_note_spending,
};

// Verify an anonymous presentation
let valid = verify_anonymous_presentation(&presentation, &expected_federation_root);

// Verify non-revocation
verify_non_revocation_proof(&non_rev_proof).unwrap();

// Verify note spending (for note tree operators)
verify_note_spending(nullifier_bb, merkle_root_bb, &spending_proof).unwrap();

For the architectural design behind these privacy primitives, see Privacy Architecture.