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::StealthMetaAddress;

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

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

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

    // Example output:
    // stealth1Abc123...

    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::{PublicMetaAddress, StealthPayment};

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

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

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

    // 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::{StealthMetaAddress, Scanner, Announcement};

fn scan_payments(announcements: &[Announcement]) -> anyhow::Result<()> {
    // Load meta-address (with private keys)
    let meta = StealthMetaAddress::load_from_file("~/.onyx/keys.json")?;

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

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

    Ok(())
}

4. Spend from Stealth Address

Derive the spending key and transfer funds:

spend.rs
rust
use onyx_sdk::{StealthMetaAddress, StealthKeypair};

fn spend_payment(meta: &StealthMetaAddress, ephemeral_pubkey: &[u8; 32]) -> anyhow::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::{StealthMetaAddress, StealthPayment, StealthKeypair, Scanner, Announcement};

fn main() {
    // === RECEIVER SETUP ===
    let receiver_meta = StealthMetaAddress::generate();
    let public_meta = receiver_meta.public_meta_address();
    println!("Receiver meta-address: {}", public_meta.to_string());

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

    // === RECEIVER DETECTS PAYMENT ===
    let announcement = Announcement {
        ephemeral_pubkey: payment.ephemeral_pubkey,
        stealth_address: payment.stealth_address,
        timestamp: 0,
    };
    let scanner = Scanner::new(&receiver_meta);
    let detected = scanner.scan_announcements_list(&[announcement]).unwrap();
    assert_eq!(detected.len(), 1);
    println!("Payment detected!");

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