Sentinel safety validation plugin for Solana Agent Kit - THSP protocol for AI agent transaction safety
npm install @sentinelseed/solana-agent-kitbash
npm install @sentinelseed/solana-agent-kit
`
Peer Dependencies:
`bash
npm install solana-agent-kit @solana/web3.js
`
Quick Start
`typescript
import { SolanaAgentKit } from "solana-agent-kit";
import SentinelPlugin from "@sentinelseed/solana-agent-kit";
const agent = new SolanaAgentKit(privateKey, rpcUrl)
.use(SentinelPlugin());
// Validate before any transaction
const result = await agent.methods.validateTransaction({
action: "transfer",
amount: 50,
recipient: "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
purpose: "Payment for NFT purchase",
});
if (result.shouldProceed) {
// Safe to execute
} else {
console.log("Blocked:", result.concerns);
}
`
Configuration
`typescript
import SentinelPlugin from "@sentinelseed/solana-agent-kit";
const agent = new SolanaAgentKit(privateKey, rpcUrl)
.use(SentinelPlugin({
// Maximum amount per transaction (default: 100)
maxTransactionAmount: 100,
// Require confirmation above this amount (default: 10)
confirmationThreshold: 10,
// Actions requiring explicit purpose (default shown)
requirePurposeFor: ["transfer", "swap", "approve", "bridge", "withdraw", "stake"],
// Block all transactions with any concerns (default: false)
strictMode: false,
// Known scam addresses to block
blockedAddresses: [
"ScamWa11etAddress111111111111111111111111111",
],
// Only allow these programs (empty = all allowed)
allowedPrograms: [],
// Custom patterns to detect
customPatterns: [
{
name: "high_slippage",
pattern: /slippage.*(?:[5-9]\d|100)%/i,
riskLevel: "high",
message: "High slippage tolerance detected",
},
],
// Callback for monitoring
onValidation: (result) => {
console.log([Sentinel] ${result.metadata.action}: ${result.riskLevel});
},
}));
`
THSP Protocol
Every transaction is validated against four gates:
| Gate | Question | Checks |
|------|----------|--------|
| Truth | Is the data accurate? | Address format, valid amounts, program IDs |
| Harm | Could this cause damage? | Blocked addresses, high-risk actions, program whitelist |
| Scope | Is this within limits? | Amount limits, rate limits |
| Purpose | Is there legitimate benefit? | Explicit justification for sensitive operations |
All gates must pass for a transaction to be approved.
Available Actions
These actions are automatically available when using the plugin:
$3
Full validation with detailed gate analysis.
`typescript
const result = await agent.methods.validateTransaction({
action: "transfer",
amount: 50,
recipient: "...",
purpose: "Payment for services",
});
// Returns:
{
safe: boolean,
shouldProceed: boolean,
requiresConfirmation: boolean,
riskLevel: "low" | "medium" | "high" | "critical",
concerns: string[],
recommendations: string[],
gateResults: [
{ gate: "truth", passed: true },
{ gate: "harm", passed: true },
{ gate: "scope", passed: true },
{ gate: "purpose", passed: true },
],
}
`
$3
Quick pass/fail check.
`typescript
const isSafe = await agent.methods.checkSafety("transfer", 10, recipient);
`
$3
Validation statistics and configuration.
`typescript
const status = await agent.methods.getSafetyStatus();
console.log(status.stats.blockRate); // e.g., 0.05 (5%)
`
$3
Manage the address blocklist.
`typescript
await agent.methods.blockAddress("ScamAddress...");
await agent.methods.unblockAddress("VerifiedAddress...");
`
LangChain Integration
The plugin works seamlessly with LangChain agents:
`typescript
import { SolanaAgentKit, createSolanaTools } from "solana-agent-kit";
import TokenPlugin from "@solana-agent-kit/plugin-token";
import SentinelPlugin from "@sentinelseed/solana-agent-kit";
const agent = new SolanaAgentKit(privateKey, rpcUrl)
.use(TokenPlugin)
.use(SentinelPlugin());
// Create tools including Sentinel actions
const tools = createSolanaTools(agent);
// Use with your LangChain agent
const executor = new AgentExecutor({ agent: reactAgent, tools });
await executor.invoke({
input:
,
});
`
Risk Levels
| Level | Description | Action |
|-------|-------------|--------|
| low | No concerns detected | Proceed |
| medium | Minor concerns | Proceed with caution |
| high | Significant concerns | Review carefully |
| critical | Serious issues detected | Blocked |
Default Suspicious Patterns
The plugin detects these patterns automatically:
- Drain operations: drain, sweep, empty
- Unlimited approvals: unlimited, infinite approval
- Bulk transfers: transfer all, send entire
- Private key exposure: private key, seed phrase, mnemonic
- Suspicious urgency: urgent, immediately, asap
API Reference
$3
Creates the plugin instance.
$3
Core validation engine, available for direct use:
`typescript
import { SentinelValidator } from "@sentinelseed/solana-agent-kit";
const validator = new SentinelValidator({
maxTransactionAmount: 100,
});
const result = validator.validate({
action: "transfer",
amount: 50,
recipient: "...",
});
`
$3
`typescript
import type {
SafetyValidationResult,
ValidationInput,
SentinelPluginConfig,
RiskLevel,
THSPGate,
} from "@sentinelseed/solana-agent-kit";
`
Examples
See the examples directory:
- basic-usage.ts - Simple integration
- langchain-integration.ts - LangChain agent setup
- defi-safety.ts` - DeFi-specific configuration