Nexwave Kernel

Tagline: "I don't think. I execute."

Nexwave Kernel is a deterministic DeFi execution kernel for Solana. It receives structured intents (e.g., swap 500 USDC for SOL with max 0.5% slippage), validates constraints, simulates via Jupiter, executes on-chain, and returns verified outcomes.

This kernel is designed to be called by external services (like Clawdbot skills) via HTTP. It does NOT handle natural language — it receives structured intent objects and returns structured results.

Features

• ✅ Deterministic Execution: Validates constraints before execution
• ✅ Jupiter Integration: Fetches real-time quotes and executes swaps
• ✅ Constraint Validation: Enforces slippage limits, deadlines, minimum outputs
• ✅ Transaction Simulation: Simulates on-chain before execution
• ✅ Structured Logging: JSON-formatted logs for all operations
• ✅ Error Handling: Clear, actionable error messages with recoverability flags

Tech Stack

• Runtime: Bun
• Language: TypeScript (strict mode)
• HTTP Framework: Hono
• Solana: @solana/web3.js
• Jupiter: @jup-ag/api (v6)
• Validation: Zod
• Base58 Encoding: bs58

Installation

cd ~/var/www/nexwave-kernel
bun install

Configuration

Copy .env.example to .env and configure:

cp .env.example .env

Edit .env:

# Solana RPC endpoint (using Helius for better performance)
# Get your API key from: https://www.helius.dev/
SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_HELIUS_API_KEY

# Wallet private key (base58 encoded)
# Export from Phantom: Settings > Export Private Key
# Or generate with: solana-keygen new
WALLET_PRIVATE_KEY=your_base58_private_key_here

# Server port
PORT=3456

# Helius API Configuration (optional - for enhanced features)
HELIUS_API_KEY=YOUR_HELIUS_API_KEY
HELIUS_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_HELIUS_API_KEY

Recommended: Use Helius RPC instead of the public endpoint for:

• Higher rate limits
• Better reliability
• Faster transaction processing
• Priority routing

Running

Development (with hot reload)

bun run dev

Production

bun start

The server will start on http://localhost:3456.

API Endpoints

GET /health

Check kernel health status.

Response:

{
  "status": "ok",
  "version": "0.1.0",
  "solanaConnected": true,
  "jupiterConnected": true
}

POST /intent/simulate

Validate constraints and simulate a swap without executing.

Request:

{
  "action": "swap",
  "inputToken": "USDC",
  "outputToken": "SOL",
  "amount": "100",
  "constraints": {
    "maxSlippageBps": 50,
    "deadlineMs": 1706400000000,
    "minOutput": "0.8"
  }
}

Success Response:

{
  "success": true,
  "quote": {
    "inputAmount": "100",
    "outputAmount": "0.802451275",
    "priceImpactPct": 0.00018500503912435758,
    "slippageBps": 50,
    "route": ["USDC", "SOL"]
  }
}

Error Response (constraint violation):

{
  "success": false,
  "error": "Slippage 80bps exceeds max 50bps",
  "recoverable": true
}

POST /intent/execute

Validate, simulate, and execute a swap on-chain.

Request: Same as /intent/simulate

Success Response:

{
  "success": true,
  "txHash": "5xyz...",
  "explorerUrl": "https://solscan.io/tx/5xyz...",
  "outcome": {
    "inputAmount": "100",
    "outputAmount": "0.802451275",
    "actualSlippageBps": 28
  }
}

Error Response:

{
  "success": false,
  "error": "Wallet not configured",
  "recoverable": false
}

Supported Tokens

The kernel includes a built-in registry of common Solana tokens:

• SOL - Solana (wrapped)
• USDC - USD Coin
• USDT - Tether USD
• BONK - Bonk
• JUP - Jupiter

You can also use Solana mint addresses directly.

Constraint Validation

Before execution, the kernel validates:

1. Deadline (if provided): Must be in the future
2. Max Slippage: Must be between 1-500 bps (0.01% - 5%)
3. Amount: Must be positive
4. Tokens: Must be recognized (in registry or valid Solana address)

After simulation, before execution:

1. Slippage Check: Simulated slippage must be ≤ maxSlippageBps
2. Min Output (if provided): Simulated output must be ≥ minOutput

Testing

Test Simulate Endpoint

curl -X POST http://localhost:3456/intent/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "action": "swap",
    "inputToken": "USDC",
    "outputToken": "SOL",
    "amount": "100",
    "constraints": {
      "maxSlippageBps": 50
    }
  }'

Test Constraint Validation

# Test invalid slippage (too high)
curl -X POST http://localhost:3456/intent/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "action": "swap",
    "inputToken": "USDC",
    "outputToken": "SOL",
    "amount": "100",
    "constraints": {
      "maxSlippageBps": 600
    }
  }'

# Expected: Error "Max slippage must not exceed 500bps (5%)"

Directory Structure

nexwave-kernel/
├── src/
│   ├── index.ts              # Hono server entry point
│   ├── routes/
│   │   ├── intent.ts         # POST /intent/simulate, POST /intent/execute
│   │   └── health.ts         # GET /health
│   ├── core/
│   │   ├── types.ts          # Intent, Constraint, ExecutionResult types
│   │   ├── validator.ts      # Zod schemas + constraint validation
│   │   ├── simulator.ts      # Jupiter quote fetching + simulation
│   │   └── executor.ts       # Transaction building, signing, sending
│   ├── adapters/
│   │   └── jupiter.ts        # Jupiter API wrapper
│   └── utils/
│       ├── tokens.ts         # Token mint addresses, decimals lookup
│       └── logger.ts         # Structured logging
├── .env.example
├── .env
├── package.json
├── tsconfig.json
└── README.md

Error Handling

All errors include:

• success: boolean (always false for errors)
• error: string (human-readable error message)
• recoverable: boolean (whether retrying might succeed)

Recoverable errors (temporary, can retry):

• Network issues
• Slippage too tight for current market
• Insufficient liquidity

Non-recoverable errors (permanent, don't retry):

• Invalid token
• Wallet not configured
• Invalid intent format

Logging

All logs are JSON-formatted with:

• timestamp: ISO 8601 timestamp
• level: "info" | "warn" | "error" | "debug"
• message: Human-readable message
• data: Structured data (optional)

Example:

{
  "timestamp": "2026-01-27T02:36:30.814Z",
  "level": "info",
  "message": "Nexwave Kernel starting",
  "data": {
    "version": "0.1.0",
    "port": 3456,
    "rpcUrl": "https://api.mainnet-beta.solana.com"
  }
}

Security

• Private keys are never logged or exposed in responses
• All transactions are simulated before execution
• Constraint validation happens before any on-chain interaction
• Failed transactions don't consume SOL (simulation catches errors)

Live Integration: Clawdbot Telegram Skill

A Clawdbot skill (~/.clawdbot/skills/nexwave/) enables natural language DeFi trading via Telegram:

Example conversation:

User: "Swap 0.01 SOL for USDC"
Bot:  "⚡ Quote: 0.01 SOL → 1.27 USDC
       Slippage: 0.5% | Price Impact: 0.00%
       Reply 'yes' to execute"
User: "yes"
Bot:  "⚡ Executed! TX: https://solscan.io/tx/5xyz..."

The skill handles:

• Natural language parsing → structured intents
• Simulation-first workflow (always shows quote)
• User confirmation requirement
• Transaction result formatting

Integration Example Code

// Simulate a swap
const simulation = await fetch('http://localhost:3456/intent/simulate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    action: 'swap',
    inputToken: 'USDC',
    outputToken: 'SOL',
    amount: '500',
    constraints: { maxSlippageBps: 50 }
  })
});

const result = await simulation.json();

if (result.success) {
  console.log(`Quote: ${result.quote.outputAmount} SOL`);
  console.log(`Slippage: ${result.quote.slippageBps}bps`);

  // Ask user for confirmation, then execute
  const execution = await fetch('http://localhost:3456/intent/execute', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(intent)
  });

  const execResult = await execution.json();
  if (execResult.success) {
    console.log(`TX: ${execResult.explorerUrl}`);
  }
}

Development Notes

• Bun automatically loads .env (no need for dotenv)
• TypeScript runs with strict mode enabled
• All validation uses Zod schemas
• Jupiter API client is initialized per-request for thread safety

Future Enhancements

• Limit orders
• Bot orchestration (launch/monitor/kill trading bots)
• Multi-chain execution
• Position monitoring
• Portfolio rebalancing

License

MIT

Support

For issues or questions, check the logs:

tail -f /tmp/nexwave-kernel.log

---

Built for the Nexwave ecosystem. I don't think. I execute. ⚡