sclaw-agent 1.0.0

package/dist/server/lib/helius.js

@@ -0,0 +1,96 @@
+import { HELIUS_RPC_URL, HELIUS_API_KEY, HELIUS_API_URL } from '../config';
+export async function heliusRpc(request) {
+    const res = await fetch(HELIUS_RPC_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 1,
+            method: request.method,
+            params: request.params,
+        }),
+    });
+    const data = await res.json();
+    if (data.error)
+        throw new Error(data.error.message);
+    return data.result;
+}
+export async function simulateTransaction(encodedTx) {
+    const result = await heliusRpc({
+        method: 'simulateTransaction',
+        params: [
+            encodedTx,
+            {
+                encoding: 'base64',
+                commitment: 'confirmed',
+                replaceRecentBlockhash: true,
+                accounts: {
+                    encoding: 'jsonParsed',
+                    addresses: [],
+                },
+            },
+        ],
+    });
+    return {
+        success: result.value.err === null,
+        logs: result.value.logs || [],
+        unitsConsumed: result.value.unitsConsumed || 0,
+        error: result.value.err ? JSON.stringify(result.value.err) : null,
+        accounts: result.value.accounts || [],
+    };
+}
+export async function getTokenMetadata(mintAddress) {
+    const res = await fetch(`${HELIUS_API_URL}/token-metadata?api-key=${HELIUS_API_KEY}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            mintAccounts: [mintAddress],
+            includeOffChain: true,
+            disableCache: false,
+        }),
+    });
+    return res.json();
+}
+export async function getAsset(assetId) {
+    const res = await fetch(HELIUS_RPC_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'getAsset',
+            params: { id: assetId },
+        }),
+    });
+    const data = await res.json();
+    return data.result;
+}
+export async function getBalance(address) {
+    const result = await heliusRpc({
+        method: 'getBalance',
+        params: [address],
+    });
+    return result.value;
+}
+export async function getTokenAccounts(ownerAddress) {
+    const result = await heliusRpc({
+        method: 'getTokenAccountsByOwner',
+        params: [
+            ownerAddress,
+            { programId: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' },
+            { encoding: 'jsonParsed' },
+        ],
+    });
+    return result;
+}
+export async function getTransactionHistory(address, limit = 10) {
+    const res = await fetch(`${HELIUS_API_URL}/addresses/${address}/transactions?api-key=${HELIUS_API_KEY}&limit=${limit}`);
+    return res.json();
+}
+export async function getParsedTransaction(signature) {
+    const result = await heliusRpc({
+        method: 'getTransaction',
+        params: [signature, { encoding: 'jsonParsed', maxSupportedTransactionVersion: 0 }],
+    });
+    return result;
+}

package/dist/server/lib/token-analysis.d.ts

@@ -0,0 +1,24 @@
+export interface TokenSecurityReport {
+    mint: string;
+    name: string | null;
+    symbol: string | null;
+    supply: number | null;
+    decimals: number | null;
+    freezeAuthority: string | null;
+    mintAuthority: string | null;
+    isFreezable: boolean;
+    isMintable: boolean;
+    topHolders: {
+        address: string;
+        amount: number;
+        percentage: number;
+    }[];
+    holderConcentration: number;
+    lpInfo: {
+        locked: boolean;
+        pool: string | null;
+    } | null;
+    metadata: unknown;
+    risks: string[];
+}
+export declare function analyzeToken(mintAddress: string): Promise<TokenSecurityReport>;

package/dist/server/lib/token-analysis.js

@@ -0,0 +1,84 @@
+import { heliusRpc, getTokenMetadata } from './helius';
+export async function analyzeToken(mintAddress) {
+    const risks = [];
+    const mintInfo = await heliusRpc({
+        method: 'getAccountInfo',
+        params: [mintAddress, { encoding: 'jsonParsed' }],
+    });
+    const parsed = mintInfo?.value?.data?.parsed?.info;
+    const mintAuthority = parsed?.mintAuthority || null;
+    const freezeAuthority = parsed?.freezeAuthority || null;
+    const supply = parsed?.supply ? Number(parsed.supply) : null;
+    const decimals = parsed?.decimals ?? null;
+    const isMintable = mintAuthority !== null;
+    const isFreezable = freezeAuthority !== null;
+    if (isMintable)
+        risks.push('MINT_AUTHORITY_ACTIVE — token supply can be increased');
+    if (isFreezable)
+        risks.push('FREEZE_AUTHORITY_ACTIVE — accounts can be frozen');
+    let name = null;
+    let symbol = null;
+    let metadata = null;
+    try {
+        const metaResult = await getTokenMetadata(mintAddress);
+        if (metaResult?.[0]) {
+            metadata = metaResult[0];
+            name = metaResult[0]?.onChainMetadata?.metadata?.data?.name ||
+                metaResult[0]?.offChainMetadata?.metadata?.name || null;
+            symbol = metaResult[0]?.onChainMetadata?.metadata?.data?.symbol ||
+                metaResult[0]?.offChainMetadata?.metadata?.symbol || null;
+        }
+    }
+    catch {
+        risks.push('METADATA_FETCH_FAILED — could not retrieve token metadata');
+    }
+    let topHolders = [];
+    let holderConcentration = 0;
+    try {
+        const holders = await heliusRpc({
+            method: 'getTokenLargestAccounts',
+            params: [mintAddress],
+        });
+        const totalSupply = supply && decimals !== null ? supply / Math.pow(10, decimals) : 0;
+        topHolders = (holders?.value || []).slice(0, 10).map((h) => {
+            const amount = Number(h.amount) / Math.pow(10, decimals || 0);
+            const percentage = totalSupply > 0 ? (amount / totalSupply) * 100 : 0;
+            return {
+                address: h.address,
+                amount,
+                percentage: Math.round(percentage * 100) / 100,
+            };
+        });
+        holderConcentration = topHolders.reduce((sum, h) => sum + h.percentage, 0);
+        holderConcentration = Math.round(holderConcentration * 100) / 100;
+        if (holderConcentration > 80) {
+            risks.push(`HIGH_CONCENTRATION — top 10 holders own ${holderConcentration}% of supply`);
+        }
+        else if (holderConcentration > 50) {
+            risks.push(`MODERATE_CONCENTRATION — top 10 holders own ${holderConcentration}% of supply`);
+        }
+        const bigWhale = topHolders.find(h => h.percentage > 20);
+        if (bigWhale) {
+            risks.push(`WHALE_ALERT — single holder owns ${bigWhale.percentage}% (${bigWhale.address.slice(0, 8)}...)`);
+        }
+    }
+    catch {
+        risks.push('HOLDER_ANALYSIS_FAILED — could not fetch holder data');
+    }
+    return {
+        mint: mintAddress,
+        name,
+        symbol,
+        supply,
+        decimals,
+        freezeAuthority,
+        mintAuthority,
+        isFreezable,
+        isMintable,
+        topHolders,
+        holderConcentration,
+        lpInfo: null,
+        metadata,
+        risks,
+    };
+}

package/dist/server/routes/risk.d.ts

@@ -0,0 +1 @@
+export declare const riskRoute: import("express-serve-static-core").Router;

package/dist/server/routes/risk.js

@@ -0,0 +1,57 @@
+import { Router } from 'express';
+import { getBalance, getTokenAccounts, getTransactionHistory } from '../lib/helius';
+import { clawAnalyze } from '../lib/claw-agent';
+export const riskRoute = Router();
+riskRoute.get('/wallet/:address', async (req, res) => {
+    try {
+        const { address } = req.params;
+        const results = await Promise.allSettled([
+            getBalance(address),
+            getTokenAccounts(address),
+            getTransactionHistory(address, 5),
+        ]);
+        const balance = results[0].status === 'fulfilled' ? results[0].value : 0;
+        const tokenAccounts = results[1].status === 'fulfilled' ? results[1].value : { value: [] };
+        const recentTxs = results[2].status === 'fulfilled' ? results[2].value : [];
+        const txSummary = recentTxs?.map((tx) => ({
+            type: tx.type,
+            source: tx.source,
+            fee: tx.fee,
+            description: tx.description?.slice(0, 200),
+            timestamp: tx.timestamp,
+        })) || [];
+        const clawReport = await clawAnalyze(JSON.stringify({
+            type: 'WALLET_RISK_ANALYSIS',
+            address,
+            balanceSOL: balance / 1e9,
+            tokenAccountCount: tokenAccounts?.value?.length || 0,
+            recentTransactionSummary: txSummary,
+        }));
+        res.json({
+            address,
+            balanceSOL: balance / 1e9,
+            tokenAccounts,
+            recentTransactions: recentTxs,
+            clawAnalysis: clawReport,
+        });
+    }
+    catch (err) {
+        res.status(500).json({ error: err.message || 'Wallet analysis failed' });
+    }
+});
+riskRoute.post('/analyze', async (req, res) => {
+    try {
+        const { data, context } = req.body;
+        if (!data) {
+            return res.status(400).json({ error: 'Missing data for analysis' });
+        }
+        const clawReport = await clawAnalyze(JSON.stringify({
+            type: context || 'CUSTOM_ANALYSIS',
+            data,
+        }));
+        res.json({ clawAnalysis: clawReport });
+    }
+    catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});

package/dist/server/routes/simulate.d.ts

@@ -0,0 +1 @@
+export declare const simulateRoute: import("express-serve-static-core").Router;

package/dist/server/routes/simulate.js

@@ -0,0 +1,60 @@
+import { Router } from 'express';
+import { simulateTransaction, getBalance, getParsedTransaction } from '../lib/helius';
+import { clawAnalyze } from '../lib/claw-agent';
+export const simulateRoute = Router();
+simulateRoute.post('/transaction', async (req, res) => {
+    try {
+        const { transaction, walletAddress } = req.body;
+        if (!transaction) {
+            return res.status(400).json({ error: 'Missing transaction (base64 encoded)' });
+        }
+        let preBalance = null;
+        if (walletAddress) {
+            preBalance = await getBalance(walletAddress);
+        }
+        const simResult = await simulateTransaction(transaction);
+        let estimatedCost = null;
+        if (preBalance !== null && simResult.unitsConsumed > 0) {
+            estimatedCost = simResult.unitsConsumed * 0.000005;
+        }
+        const clawReport = await clawAnalyze(JSON.stringify({
+            type: 'TRANSACTION_SIMULATION',
+            success: simResult.success,
+            logs: simResult.logs,
+            unitsConsumed: simResult.unitsConsumed,
+            error: simResult.error,
+            walletAddress,
+            preBalance: preBalance ? preBalance / 1e9 : null,
+            estimatedCostSOL: estimatedCost,
+        }));
+        res.json({
+            simulation: simResult,
+            preBalance: preBalance ? preBalance / 1e9 : null,
+            estimatedCostSOL: estimatedCost,
+            clawAnalysis: clawReport,
+        });
+    }
+    catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+simulateRoute.post('/preview', async (req, res) => {
+    try {
+        const { signature } = req.body;
+        if (!signature) {
+            return res.status(400).json({ error: 'Missing transaction signature' });
+        }
+        const txData = await getParsedTransaction(signature);
+        const clawReport = await clawAnalyze(JSON.stringify({
+            type: 'TRANSACTION_REVIEW',
+            transaction: txData,
+        }));
+        res.json({
+            transaction: txData,
+            clawAnalysis: clawReport,
+        });
+    }
+    catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});

package/dist/server/routes/token.d.ts

@@ -0,0 +1 @@
+export declare const tokenRoute: import("express-serve-static-core").Router;

package/dist/server/routes/token.js

@@ -0,0 +1,36 @@
+import { Router } from 'express';
+import { analyzeToken } from '../lib/token-analysis';
+import { getTransactionHistory } from '../lib/helius';
+import { clawAnalyze } from '../lib/claw-agent';
+export const tokenRoute = Router();
+tokenRoute.get('/:mint', async (req, res) => {
+    try {
+        const { mint } = req.params;
+        if (!mint || mint.length < 32) {
+            return res.status(400).json({ error: 'Invalid mint address' });
+        }
+        const report = await analyzeToken(mint);
+        const clawReport = await clawAnalyze(JSON.stringify({
+            type: 'TOKEN_SECURITY_ANALYSIS',
+            ...report,
+        }));
+        res.json({
+            token: report,
+            clawAnalysis: clawReport,
+        });
+    }
+    catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+tokenRoute.get('/:mint/history', async (req, res) => {
+    try {
+        const { mint } = req.params;
+        const limit = parseInt(req.query.limit) || 10;
+        const history = await getTransactionHistory(mint, limit);
+        res.json({ history });
+    }
+    catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "sclaw-agent",
+  "version": "1.0.0",
+  "description": "SCLAW — ShadowClawAI Pre-Execution Engine. Simulate Solana transactions, analyze token security, get AI risk reports.",
+  "type": "module",
+  "main": "server/index.ts",
+  "bin": {
+    "sclaw": "./dist/cli/index.js"
+  },
+  "scripts": {
+    "server": "npx tsx server/index.ts",
+    "cli": "npx tsx cli/index.ts",
+    "build": "npx tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "solana",
+    "transaction",
+    "simulator",
+    "security",
+    "ai",
+    "claw",
+    "helius",
+    "token",
+    "risk",
+    "pre-execution",
+    "blockchain",
+    "defi",
+    "web3"
+  ],
+  "author": "sclaw-ai",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alc0hol120/SHADOWCLAW"
+  },
+  "homepage": "https://github.com/alc0hol120/SHADOWCLAW",
+  "files": [
+    "dist",
+    "server",
+    "cli",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@solana/web3.js": "^1.98.4",
+    "cors": "^2.8.6",
+    "express": "^5.2.1"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/node": "^24.12.0",
+    "tsx": "^4.21.0",
+    "typescript": "~5.9.3"
+  }
+}

package/server/config.ts

@@ -0,0 +1,5 @@
+export const HELIUS_API_KEY = process.env.HELIUS_API_KEY || '';
+export const HELIUS_RPC_URL = `https://mainnet.helius-rpc.com/?api-key=${HELIUS_API_KEY}`;
+export const HELIUS_API_URL = `https://api.helius.xyz/v0`;
+export const OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY || '';
+export const OPENROUTER_URL = 'https://openrouter.ai/api/v1/chat/completions';

package/server/index.ts

@@ -0,0 +1,23 @@
+import express from 'express';
+import cors from 'cors';
+import { simulateRoute } from './routes/simulate';
+import { tokenRoute } from './routes/token';
+import { riskRoute } from './routes/risk';
+
+const app = express();
+const PORT = process.env.PORT || 3001;
+
+app.use(cors());
+app.use(express.json());
+
+app.use('/api/simulate', simulateRoute);
+app.use('/api/token', tokenRoute);
+app.use('/api/risk', riskRoute);
+
+app.get('/api/health', (_req, res) => {
+  res.json({ status: 'CLAW Engine Online', version: '1.0.0' });
+});
+
+app.listen(PORT, () => {
+  console.log(`[CLAW] ShadowClaw engine running on port ${PORT}`);
+});

package/server/lib/claw-agent.ts

@@ -0,0 +1,78 @@
+import { OPENROUTER_API_KEY, OPENROUTER_URL } from '../config';
+
+const CLAW_SYSTEM_PROMPT = `You are CLAW (ShadowClawAI), a specialized AI agent for blockchain transaction analysis and risk assessment.
+
+Your role:
+- Analyze transaction simulation results and identify risks
+- Detect potential rug pulls, honeypots, and scam patterns
+- Assess smart contract risks based on on-chain data
+- Provide clear, actionable risk reports
+
+Rules:
+- Be direct and precise. No fluff.
+- Always provide a risk score from 0-100 (0 = safe, 100 = extreme danger)
+- Categorize risks: SAFE, LOW, MEDIUM, HIGH, CRITICAL
+- Flag specific red flags with evidence
+- Never give financial advice, only technical risk analysis
+- Use real data only, never fabricate information`;
+
+export interface ClawAnalysis {
+  riskScore: number;
+  riskLevel: 'SAFE' | 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+  summary: string;
+  flags: string[];
+  details: string;
+}
+
+export async function clawAnalyze(context: string): Promise<ClawAnalysis> {
+  const res = await fetch(OPENROUTER_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${OPENROUTER_API_KEY}`,
+      'HTTP-Referer': 'https://sclaw.ai',
+      'X-Title': 'SCLAW - ShadowClawAI',
+    },
+    body: JSON.stringify({
+      model: 'anthropic/claude-sonnet-4',
+      messages: [
+        { role: 'system', content: CLAW_SYSTEM_PROMPT },
+        {
+          role: 'user',
+          content: `Analyze the following blockchain data and provide a risk assessment. Respond ONLY with valid JSON matching this schema:
+{
+  "riskScore": number (0-100),
+  "riskLevel": "SAFE" | "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
+  "summary": "one-line summary",
+  "flags": ["array of specific red flags"],
+  "details": "detailed analysis"
+}
+
+Data to analyze:
+${context}`,
+        },
+      ],
+      temperature: 0.1,
+      max_tokens: 2000,
+    }),
+  });
+
+  const data = await res.json();
+  const content = data.choices?.[0]?.message?.content || '';
+
+  try {
+    const jsonMatch = content.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+      return JSON.parse(jsonMatch[0]);
+    }
+  } catch {
+  }
+
+  return {
+    riskScore: -1,
+    riskLevel: 'MEDIUM',
+    summary: 'CLAW agent could not complete analysis',
+    flags: ['Analysis incomplete — review manually'],
+    details: content,
+  };
+}

package/server/lib/helius.ts

@@ -0,0 +1,117 @@
+import { HELIUS_RPC_URL, HELIUS_API_KEY, HELIUS_API_URL } from '../config';
+
+interface HeliusRpcRequest {
+  method: string;
+  params: unknown[];
+}
+
+export async function heliusRpc(request: HeliusRpcRequest): Promise<unknown> {
+  const res = await fetch(HELIUS_RPC_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: request.method,
+      params: request.params,
+    }),
+  });
+  const data = await res.json();
+  if (data.error) throw new Error(data.error.message);
+  return data.result;
+}
+
+export async function simulateTransaction(encodedTx: string): Promise<{
+  success: boolean;
+  logs: string[];
+  unitsConsumed: number;
+  error: string | null;
+  accounts: unknown[];
+}> {
+  const result = await heliusRpc({
+    method: 'simulateTransaction',
+    params: [
+      encodedTx,
+      {
+        encoding: 'base64',
+        commitment: 'confirmed',
+        replaceRecentBlockhash: true,
+        accounts: {
+          encoding: 'jsonParsed',
+          addresses: [],
+        },
+      },
+    ],
+  }) as any;
+
+  return {
+    success: result.value.err === null,
+    logs: result.value.logs || [],
+    unitsConsumed: result.value.unitsConsumed || 0,
+    error: result.value.err ? JSON.stringify(result.value.err) : null,
+    accounts: result.value.accounts || [],
+  };
+}
+
+export async function getTokenMetadata(mintAddress: string): Promise<unknown> {
+  const res = await fetch(`${HELIUS_API_URL}/token-metadata?api-key=${HELIUS_API_KEY}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      mintAccounts: [mintAddress],
+      includeOffChain: true,
+      disableCache: false,
+    }),
+  });
+  return res.json();
+}
+
+export async function getAsset(assetId: string): Promise<unknown> {
+  const res = await fetch(HELIUS_RPC_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'getAsset',
+      params: { id: assetId },
+    }),
+  });
+  const data = await res.json();
+  return data.result;
+}
+
+export async function getBalance(address: string): Promise<number> {
+  const result = await heliusRpc({
+    method: 'getBalance',
+    params: [address],
+  }) as any;
+  return result.value;
+}
+
+export async function getTokenAccounts(ownerAddress: string): Promise<unknown> {
+  const result = await heliusRpc({
+    method: 'getTokenAccountsByOwner',
+    params: [
+      ownerAddress,
+      { programId: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' },
+      { encoding: 'jsonParsed' },
+    ],
+  });
+  return result;
+}
+
+export async function getTransactionHistory(address: string, limit = 10): Promise<unknown> {
+  const res = await fetch(
+    `${HELIUS_API_URL}/addresses/${address}/transactions?api-key=${HELIUS_API_KEY}&limit=${limit}`
+  );
+  return res.json();
+}
+
+export async function getParsedTransaction(signature: string): Promise<unknown> {
+  const result = await heliusRpc({
+    method: 'getTransaction',
+    params: [signature, { encoding: 'jsonParsed', maxSupportedTransactionVersion: 0 }],
+  });
+  return result;
+}