ngit-grasp/grasp-audit/QUICK_START.md

GRASP Audit - Quick Start Guide

Prerequisites

• Rust 1.75 or later
• C compiler (gcc or clang)
• A Nostr relay for testing (optional for unit tests)

Setup on NixOS

# Enter development shell
cd grasp-audit
nix develop

# Build the project
cargo build

# Run unit tests (no relay needed)
cargo test --lib

Setup on Other Systems

cd grasp-audit

# Install Rust (if needed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Build
cargo build

# Run unit tests
cargo test --lib

Running Smoke Tests (Requires Relay)

Option 1: Use a Public Relay

# Run against a public relay
cargo run --example simple_audit
# Edit the example to use: wss://relay.damus.io or similar

Option 2: Run Local Relay

# Terminal 1: Start a test relay
# Option A: Using nostr-relay-builder
git clone https://github.com/rust-nostr/nostr
cd nostr/crates/nostr-relay-builder
cargo run --example basic

# Option B: Using docker
docker run -p 7000:7000 scsibug/nostr-rs-relay

# Terminal 2: Run smoke tests
cd grasp-audit
cargo run --example simple_audit

Option 3: Use the CLI

# Build the CLI
cargo build --release

# Run smoke tests
./target/release/grasp-audit audit \
  --relay ws://localhost:7000 \
  --mode ci \
  --spec nip01-smoke

Running Tests

# Unit tests only (no relay needed)
cargo test --lib

# Integration tests (needs relay at ws://localhost:7000)
cargo test --ignored

# All tests
cargo test --all

# With output
cargo test -- --nocapture

Using as a Library

Add to your Cargo.toml:

[dependencies]
grasp-audit = { path = "../grasp-audit" }

Example code:

use grasp_audit::*;

#[tokio::main]
async fn main() -> Result<()> {
    // Create audit client
    let config = AuditConfig::ci();
    let client = AuditClient::new("ws://localhost:7000", config).await?;
    
    // Run smoke tests
    let results = specs::Nip01SmokeTests::run_all(&client).await;
    
    // Print results
    results.print_report();
    
    // Check if passed
    if !results.all_passed() {
        eprintln!("Some tests failed!");
        std::process::exit(1);
    }
    
    Ok(())
}

Troubleshooting

Build Errors

Error: linker 'cc' not found

Solution (NixOS):

nix develop  # Use the provided flake.nix

Solution (Other Linux):

sudo apt-get install build-essential  # Debian/Ubuntu
sudo yum install gcc                   # RedHat/CentOS

Solution (macOS):

xcode-select --install

Connection Errors

Error: Failed to connect to relay

Solutions:

1. Make sure a relay is running at the specified URL
2. Check firewall settings
3. Try a different relay URL
4. Use ws:// for local, wss:// for remote

Test Failures

Error: Tests fail with timeout

Solutions:

1. Increase timeout in test code
2. Check relay is responding (try with websocat)
3. Check network connectivity

Examples

CI Mode (Isolated Testing)

# Each run is isolated with unique ID
./target/release/grasp-audit audit \
  --relay ws://localhost:7000 \
  --mode ci \
  --spec nip01-smoke

# Run ID: ci-a1b2c3d4-e5f6-7890-abcd-ef1234567890
# Tests only see events from this run

Production Mode (Audit Live Service)

# Read-only audit of production relay
./target/release/grasp-audit audit \
  --relay wss://relay.example.com \
  --mode production \
  --spec nip01-smoke

# Run ID: prod-audit-1699027200
# Tests see all events (including real ones)
# Minimal writes (read-only by default)

What's Next?

1. ✅ Run unit tests
2. ✅ Run smoke tests against a relay
3. ✅ Check the report output
4. 🚧 Implement GRASP-01 compliance tests
5. 🚧 Set up CI/CD integration
6. 🚧 Test against ngit-grasp relay

Resources

• README.md - Full documentation
• SMOKE_TEST_REPORT.md - Implementation details
• examples/simple_audit.rs - Example usage
• GRASP_AUDIT_PLAN.md - Original plan

Support

For issues or questions:

1. Check the documentation in this directory
2. Review the examples
3. Check the test code for usage patterns
4. Open an issue on the project repository