Architecture

SadClaw connects on-chain payments to off-chain cloud infrastructure through a hybrid architecture.

System Overview

┌─────────────────────────────────────────────────────────────────┐
│                         User / Agent                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    CLI / SDK / Website                          │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│    Solana Blockchain    │     │    SadClaw Backend      │
│  ┌───────────────────┐  │     │  ┌───────────────────┐  │
│  │ SadClaw Program   │  │     │  │ API Server        │  │
│  │ - Purchase VM     │  │────▶│  │ - Webhook listener│  │
│  │ - Extend VM       │  │     │  │ - VM provisioning │  │
│  │ - Destroy VM      │  │     │  └───────────────────┘  │
│  └───────────────────┘  │     │           │             │
│  ┌───────────────────┐  │     │           ▼             │
│  │ USDC (SPL Token)  │  │     │  ┌───────────────────┐  │
│  └───────────────────┘  │     │  │ Hetzner Cloud API │  │
│  ┌───────────────────┐  │     │  └───────────────────┘  │
│  │ NFT (Metaplex)    │  │     └─────────────────────────┘
│  └───────────────────┘  │                 │
└─────────────────────────┘                 ▼
                              ┌─────────────────────────┐
                              │      Cloud VM           │
                              │  - SSH Access           │
                              │  - Full root control    │
                              └─────────────────────────┘

Components

Solana Program

The on-chain program handles:

• Payment processing - Accepts USDC, transfers to treasury

• NFT minting - Creates Metaplex NFT for each VM

• State management - Tracks VM configs, tiers, instances

• Authorization - Verifies ownership for operations

Program ID: SADCLAWvmProgram111111111111111111111111111

Key accounts:

Account	PDA Seeds	Purpose
Config	["config"]	Global configuration
Tier	["tier", tier_id]	Pricing tier data
VM Instance	["vm", vm_id]	Individual VM state
Treasury	["treasury"]	USDC collection

Backend API

The off-chain server handles:

• Webhook processing - Listens for on-chain events

• VM provisioning - Calls cloud provider APIs

• SSH key management - Generates and stores credentials

• Health monitoring - Tracks VM status

Endpoints:

Endpoint	Method	Purpose
/api/auth/challenge	POST	Get auth challenge
/api/auth/verify	POST	Verify signature, get JWT
/api/vms	GET	List user's VMs
/api/vms/:mint	GET	Get VM details
/api/vms/:mint/ssh	GET	Get SSH credentials
/api/tiers	GET	List available tiers

Cloud Provider (Hetzner)

VMs are provisioned on Hetzner Cloud:

• Fast provisioning - VMs ready in under 2 minutes

• European data centers - Germany, Finland

• Cost effective - Competitive pricing

• API-driven - Full automation support

Purchase Flow

1. User initiates purchase (CLI/SDK/Website)
         │
         ▼
2. Transaction built with:
   - USDC transfer instruction
   - SadClaw program instruction
         │
         ▼
3. User signs transaction
         │
         ▼
4. Transaction submitted to Solana
         │
         ▼
5. On-chain:
   - USDC transferred to treasury
   - VM instance account created
   - NFT minted to user
         │
         ▼
6. Backend webhook triggered
         │
         ▼
7. Backend provisions VM on Hetzner
         │
         ▼
8. Backend updates NFT metadata with:
   - IP address
   - SSH credentials (encrypted)
   - Status: active
         │
         ▼
9. User can now SSH into VM

Security Model

On-Chain Security

• Program is immutable after deployment

• All state changes require valid signatures

• USDC transfers are atomic with VM creation

• NFT ownership verified for all operations

Off-Chain Security

• Webhook signatures verified

• SSH keys generated per-VM

• Credentials encrypted at rest

• API authentication via wallet signatures

VM Security

• Unique SSH keys per VM

• Firewall configured on provision

• No shared resources between users

• VMs isolated at hypervisor level

Data Flow

Purchase Data

User Request → Solana TX → On-chain State → Webhook → Backend → Hetzner

Query Data

User Request → Backend API → Database → Response
                    │
                    └──────→ Solana RPC → On-chain State

SSH Connection

User → CLI → Backend API → Credentials → SSH → VM

Failure Handling

Failure Point	Recovery
TX fails	USDC not transferred, retry
Webhook missed	Backend polls for new VMs
Hetzner fails	Retry provisioning, alert
VM crash	Auto-restart, notify user