API Reference

Scanner

Payment detection with full scanning, batch processing, viewing key delegation, and local payment history.

Scanner

Full-capability scanner that can detect payments and derive spending keys.

cloak_sdk::scanner

rust

pub struct Scanner {
    meta: StealthMetaAddress,
    config: ScannerConfig,
}

pub struct ScannerConfig {
    pub program_id: Pubkey,
    pub after_timestamp: Option<i64>,
    pub max_announcements: usize,
}

`Scanner::new(meta) → Scanner`

Create a scanner with default config.

let scanner = Scanner::new(&meta);

`Scanner::with_config(meta, config) → Scanner`

Create a scanner with custom configuration.

let scanner = Scanner::with_config(&meta, ScannerConfig {
    program_id: my_program_id,
    after_timestamp: Some(1709900000),
    max_announcements: 10_000,
});

`scan_announcements_list(announcements) → Result<Vec<DetectedPayment>>`

Check a slice of announcements for payments addressed to this scanner.

let detected = scanner.scan_announcements_list(&announcements)?;

`scan_announcements_batch(announcements, batch_size) → Result<Vec<DetectedPayment>>`

Process announcements in batches for large datasets.

let detected = scanner.scan_announcements_batch(&announcements, 1000)?;

`scan_with_history(announcements, history) → Result<Vec<DetectedPayment>>`

Incremental scanning — only process announcements not already in history.

let new_payments = scanner.scan_with_history(&announcements, &history)?;

`derive_spend_keypair(payment) → Result<StealthKeypair>`

Derive the spending key for a detected payment. Only available on Scanner (not on ViewingKeyScanner).

let keypair = scanner.derive_spend_keypair(&payment)?;
let solana_kp = keypair.to_solana_keypair()?;

Announcement

pub struct Announcement {
    pub stealth_address: Pubkey,
    pub ephemeral_pubkey: [u8; 32],
    pub amount: u64,
    pub timestamp: i64,
}

DetectedPayment

pub struct DetectedPayment {
    pub stealth_address: Pubkey,
    pub ephemeral_pubkey: [u8; 32],
    pub amount: Option<u64>,
    pub timestamp: Option<i64>,
    pub announcement_account: Option<Pubkey>,
    pub label: Option<String>,
    pub memo: Option<String>,
    pub spent: bool,
}

ViewingKey

A delegated key for watch-only access. Can detect payments but cannot spend.

pub struct ViewingKey {
    viewing_key: [u8; 32],
    spending_pubkey: [u8; 32],
    label: Option<String>,
}

// Create from meta-address
let vk = ViewingKey::from_meta_address(&meta);
let vk = ViewingKey::from_meta_address_with_label(&meta, "accounting");

// Serialize / deserialize
vk.save_to_file("vk.json")?;
let vk = ViewingKey::load_from_file("vk.json")?;

let s = vk.to_string();   // → "viewkey1:..."
let vk = ViewingKey::from_string(&s)?;

ViewingKeyScanner

Watch-only scanner. Same scanning API as Scanner but cannot derive spending keys.

let vk = ViewingKey::load_from_file("vk.json")?;
let scanner = ViewingKeyScanner::new(&vk);

// Can scan
let detected = scanner.scan_announcements_list(&announcements)?;

// CANNOT spend — no derive_spend_keypair() method

PaymentHistory

Local storage for detected payments with metadata.

pub struct PaymentHistory { /* ... */ }

// Create / load
let mut history = PaymentHistory::new();
let mut history = PaymentHistory::load_from_file("history.json")?;

// Add and organize payments
history.add_payment(payment);
history.set_label(&addr, "Salary");
history.set_memo(&addr, "March 2026");
history.mark_spent(&addr);

// Query
history.all_payments()        // → Vec<&DetectedPayment>
history.unspent_payments()    // → Vec<&DetectedPayment>
history.payments_by_label("Salary") // → Vec<&DetectedPayment>
history.get_payment(&addr)    // → Option<&DetectedPayment>
history.total_balance()       // → u64 (sum of unspent)
history.len()                 // → usize
history.is_empty()            // → bool

// Persist
history.save_to_file("history.json")?;