OnyxOnyx
Getting Started/Quick Start

Quick Start

Get up and running with Onyx SDK in under 5 minutes.

1. Generate a Meta-Address (Receiver)

The receiver generates a stealth meta-address and shares the public portion:

receiver.rs
rust
use onyx_sdk::prelude::*;

fn setup_receiver() -> Result<()> {
    // Generate new stealth meta-address
    let meta = StealthMetaAddress::generate()?;

    // Save privately (contains spending key!)
    meta.save("~/.onyx/keys.json")?;

    // Share publicly
    let public_meta = meta.to_public();
    println!("My stealth address: {}", public_meta.encode());

    // Example output:
    // st:sol:03a1b2c3...+02d4e5f6...

    Ok(())
}

2. Create a Stealth Payment (Sender)

The sender uses the receiver's public meta-address to create a payment:

sender.rs
rust
use onyx_sdk::prelude::*;
use solana_sdk::signature::Keypair;

fn send_payment(receiver_meta: &str, amount: u64) -> Result<()> {
    // Parse receiver's public meta-address
    let public_meta = PublicMetaAddress::decode(receiver_meta)?;

    // Create stealth payment
    let payment = StealthPayment::create(&public_meta)?;

    println!("Stealth address: {}", payment.stealth_address);
    println!("Ephemeral key: {}", bs58::encode(&payment.ephemeral_pubkey).into_string());

    // Transfer SOL to stealth address
    // (Use your preferred method: web3.js, anchor, etc.)

    // Announce the payment (publish ephemeral key)
    // This allows the receiver to detect the payment

    Ok(())
}

3. Scan for Payments (Receiver)

The receiver scans announcements to detect payments sent to them:

scan.rs
rust
use onyx_sdk::prelude::*;

fn scan_payments() -> Result<()> {
    // Load meta-address (with private keys)
    let meta = StealthMetaAddress::load("~/.onyx/keys.json")?;

    // Fetch announcements from registry
    let announcements = fetch_announcements()?;

    // Scan for payments meant for us
    let scanner = Scanner::new(&meta);
    let payments = scanner.scan(&announcements)?;

    for payment in payments {
        println!("Found payment!");
        println!("  Address: {}", payment.stealth_address);
        println!("  Amount: {} SOL", payment.amount);
    }

    Ok(())
}

4. Spend from Stealth Address

Derive the spending key and transfer funds:

spend.rs
rust
use onyx_sdk::prelude::*;

fn spend_payment(meta: &StealthMetaAddress, ephemeral_pubkey: &[u8; 32]) -> Result<()> {
    // Derive the keypair for this stealth address
    let stealth_keypair = StealthKeypair::derive(meta, ephemeral_pubkey)?;

    // Get Solana keypair for signing
    let solana_keypair = stealth_keypair.to_solana_keypair()?;

    println!("Stealth address: {}", stealth_keypair.address());

    // Now use solana_keypair to sign transactions
    // Transfer funds wherever you want

    Ok(())
}

Complete Example

main.rs
rust
use onyx_sdk::prelude::*;

fn main() -> Result<()> {
    // === RECEIVER SETUP ===
    let receiver_meta = StealthMetaAddress::generate()?;
    let public_meta = receiver_meta.to_public();
    println!("Receiver meta-address: {}", public_meta.encode());

    // === SENDER CREATES PAYMENT ===
    let payment = StealthPayment::create(&public_meta)?;
    println!("Send SOL to: {}", payment.stealth_address);

    // === RECEIVER DETECTS PAYMENT ===
    let detected = receiver_meta.try_detect(&payment.ephemeral_pubkey)?;
    assert!(detected.is_some());
    println!("Payment detected!");

    // === RECEIVER CLAIMS FUNDS ===
    let keypair = StealthKeypair::derive(&receiver_meta, &payment.ephemeral_pubkey)?;
    assert_eq!(keypair.address(), payment.stealth_address);
    println!("Can spend from: {}", keypair.address());

    Ok(())
}
InstallationConcepts