onyx-sdk 0.1.1

# Onyx SDK

**Privacy-preserving stealth addresses for Solana.**

Onyx SDK enables private payments on Solana using stealth addresses. Senders can transfer SOL to unique one-time addresses that only the intended recipient can detect and spend from, without revealing the recipient's identity on-chain.

## Features

- **Stealth Addresses** - Generate unique one-time addresses for each payment
- **Unlinkable Payments** - Observers cannot connect payments to your public identity
- **Efficient Scanning** - On-chain registry for payment detection
- **Ed25519 Compatible** - Works with Solana's native key format
- **Anchor Program** - Ready-to-deploy on-chain announcement registry

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
onyx-sdk = "0.1"
```

Or install via cargo:

```bash
cargo add onyx-sdk
```

## Quick Start

### Receiver: Generate a Stealth Meta-Address

```rust
use onyx_sdk::prelude::*;

// Generate new stealth meta-address
let meta = StealthMetaAddress::generate();

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

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

### Sender: Create a Stealth Payment

```rust
use onyx_sdk::prelude::*;

// Parse receiver's public meta-address
let public_meta = PublicMetaAddress::decode("st:sol:...")?;

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

println!("Send SOL to: {}", payment.stealth_address);
println!("Ephemeral key: {}", hex::encode(&payment.ephemeral_pubkey));

// Transfer SOL to payment.stealth_address
// Publish payment.ephemeral_pubkey to the registry
```

### Receiver: Detect and Spend

```rust
use onyx_sdk::prelude::*;

// Load your meta-address
let meta = StealthMetaAddress::load_from_file("~/.onyx/keys.json")?;

// Check if a payment is for you
if let Some(_) = meta.try_detect(&ephemeral_pubkey)? {
    // Derive the keypair to spend
    let keypair = StealthKeypair::derive(&meta, &ephemeral_pubkey)?;

    // Use keypair.to_solana_keypair() to sign transactions
    println!("Can spend from: {}", keypair.address());
}
```

## How It Works

1. **Receiver** generates a stealth meta-address (spending + viewing keypairs) and shares the public portion
2. **Sender** uses the meta-address to derive a unique stealth address and ephemeral keypair
3. **Sender** transfers SOL to the stealth address and publishes the ephemeral public key
4. **Receiver** scans ephemeral keys, detects payments meant for them, and derives the spending key

The cryptographic scheme uses ECDH (Elliptic Curve Diffie-Hellman) to create shared secrets that allow the receiver to derive the same stealth address and spending key that the sender generated.

## Project Structure

```
onyx-sdk/
├── crates/
│   ├── core/       # Main SDK library (onyx-sdk)
│   └── program/    # Anchor program (onyx-program)
└── cli/            # Command-line interface (onyx)
```

## CLI Usage

```bash
# Install
cargo install --path cli

# Generate new stealth meta-address
onyx init

# Show your public meta-address
onyx address

# Send SOL to a stealth address
onyx send <recipient-meta-address> <amount>

# Check balance
onyx balance <address>
```

## Anchor Program

The `onyx-program` provides an on-chain registry for stealth payment announcements:

- `initialize` - Create the announcement registry (PDA)
- `send_stealth` - Transfer SOL + register announcement in one transaction
- `announce` - Register an announcement without transfer

## Security

- **Private keys** are never transmitted or stored on-chain
- **Viewing keys** allow detection without spending capability
- **Spending keys** are derived deterministically from the shared secret
- Uses SHA-256 for key derivation with domain separation

## License

MIT OR Apache-2.0