bastion-how-to-use
Guides agent developers on integrating Bastion (Programmable Trust Runtime). Covers SDK usage (BastionClient), REST API endpoints (/simulate, /policy, /override, /logs), interpreting audit logs and simulation results, configuring policy rules (allowlists, SOL caps, rate limits, blockint security checks), on-chain program interaction (audit trail, agent registry, circuit breaker), and deployment. Use when the user asks about integrating an AI agent with Bastion, sending transactions through the trust runtime, configuring security policies, reading audit trails, or deploying Bastion alongside autonomous agents.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-13
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- bastion-how-to-use
- description
- Guides agent developers on integrating Bastion (Programmable Trust Runtime). Covers SDK usage (BastionClient), REST API endpoints (/simulate, /policy, /override, /logs), interpreting audit logs and simulation results, configuring policy rules (allowlists, SOL caps, rate limits, blockint security checks), on-chain program interaction (audit trail, agent registry, circuit breaker), and deployment. Use when the user asks about integrating an AI agent with Bastion, sending transactions through the trust runtime, configuring security policies, reading audit trails, or deploying Bastion alongside autonomous agents.
03 SKILL.md 正文
Bastion - How to Use (Agent Developer Guide)
Bastion is a Programmable Trust Runtime (Axum sidecar + on-chain audit programs) that sits between AI agents and their execution environments. Open-source community project developed by ZKOS Labs. Every action an agent intends to take passes through Bastion first: identity verification, policy evaluation, simulation, optionally human review, then either execute or block. Every decision recorded as a verifiable audit record.
This skill covers what an agent developer needs to integrate with Bastion.
Architecture Overview
Agent → Bastion REST API → Policy Engine → Helius Simulation → On-chain Audit → Sign or Block
↑───────────────────────────────────────────────────────────────┘ (async)
Bastion runs as a local HTTP server (default https://bastion-agentique.fly.dev/). Agents send transaction payloads to /simulate and receive a decision (ALLOW, BLOCK, or PENDING_APPROVAL).
Quick Start: Agent Integration Flow
- Start Bastion server (see README)
- Register your agent identity via
POST /agents(NEW in v0.3.0) - Configure policy (whitelist programs, set SOL caps, enable blockint checks)
- Send transactions to
POST /simulatebefore signing - If allowed, sign and send the transaction
- If blocked, request human override via
POST /override - Monitor audit logs via
GET /logs
Agent Identity & Self-Registration (v0.3.0)
Every AI agent MUST register with Bastion before sending transactions. Registration gives you a W3C DID, tracks your audit trail, and enables delegation of sub-agents.
Register (first time)
curl -s -X POST https://bastion-agentique.fly.dev//agents \
-H "Content-Type: application/json" \
-d '{
"did": "did:bastion:solana:YOUR_AGENT_PDA_BASE58",
"authority_pubkey": "YOUR_SOLANA_PUBKEY_BASE58",
"sidecar_endpoint": null
}'
If BASTION_API_KEY is set (you get 401), add: -H "X-Api-Key: YOUR_KEY"
Verify
curl -s https://bastion-agentique.fly.dev//agents | python3 -m json.tool
Spawn sub-agent (delegation)
curl -s -X POST "https://bastion-agentique.fly.dev//agents/did:bastion:solana:PARENT_DID/delegate" \
-H "Content-Type: application/json" \
-d '{
"child_did": "did:bastion:solana:CHILD_DID",
"child_name": "SubAgent-ETH",
"delegated_capabilities": ["TRANSFER"]
}'
See your delegation tree
curl -s "https://bastion-agentique.fly.dev//agents/did:bastion:solana:DID/tree" | python3 -m json.tool
Agent Registry API
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /agents |
Yes | Register agent (with optional parent_did for delegation) |
| GET | /agents |
No | List all registered agents |
| GET | /agents/:did |
No | Single agent detail |
| GET | /agents/:did/audit |
No | Agent-specific audit trail |
| GET | /agents/:did/children |
No | List sub-agents |
| GET | /agents/:did/tree |
No | Full delegation tree |
| POST | /agents/:did/delegate |
Yes | Spawn sub-agent |
| DELETE | /agents/:did/delegation/:child_did |
Yes | Revoke delegation |
| GET | /agents/:did/stake |
No | Agent stake status |
REST API Reference
POST /simulate - Validate a transaction
Request:
{
"transaction": "base64_encoded_serialized_transaction",
"intent": "human-readable description of what the agent intends to do"
}
Response 200 ALLOWED:
{
"decision": "ALLOW",
"units_consumed": 150000,
"balance_changes": {"wallet_pubkey": -1000000000},
"block_id": null
}
Response 403 BLOCKED:
{
"error": "Blockint: flash-loan pattern detected on account ...",
"decision": "BLOCK",
"block_id": "uuid-for-override"
}
The intent field is logged alongside the decision for later audit review.
POST /override - Human override for blocked transactions
{
"block_id": "uuid-from-blocked-response",
"action": "ALLOW"
}
Actions: ALLOW or REJECT.
GET /logs - Fetch audit logs
GET /logs?limit=10&offset=0&result=BLOCKED
Query params: limit (default 50), offset, result (ALLOWED/BLOCKED/PENDING_APPROVAL).
Returns:
{
"total": 142,
"offset": 0,
"limit": 10,
"entries": [
{
"id": "...",
"transaction_id": "...",
"signature": null,
"decision": "BLOCKED",
"reason": "Blockint: flash-loan pattern detected on account ...",
"block_id": "uuid",
"timestamp": 1715000000,
"intent": "Swap 1 SOL for USDC"
}
]
}
GET /logs/tx/:transaction_id - Lookup by transaction hash
GET /logs/signature/:signature - Lookup by on-chain signature
GET /policy - Current policy settings
PUT /policy - Update core policy
{
"max_sol_per_tx": 1,
"max_balance_drain_lamports": 100000000,
"rate_limit_per_minute": 10,
"simulation_checks_enabled": true,
"allowed_programs": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"],
"blocked_addresses": []
}
PUT /policy/full - Full policy update including blockint rules
All fields from /policy plus:
{
"blockint_flash_loan_check": true,
"blockint_high_slippage_check": true,
"blockint_mint_authority_blocked": true,
"blockint_freeze_authority_blocked": true,
"blockint_max_slippage_bps": 500,
"blockint_risk_labeled_addresses": []
}
Circuit breaker endpoints
GET /circuit-breaker/status- Returns{ engaged: true/false }POST /circuit-breaker/engage- Pauses all transaction processing (also callsemergencyPauseon-chain if configured)POST /circuit-breaker/disengage- Resumes (callsemergencyResumeon-chain)
GET /health - Health check (returns "Hello, Bastion!")
Policy Configuration
Program Allowlist
By default all programs are allowed (empty allowlist). Once you add entries, only whitelisted programs are permitted:
allowed_programs = [
"11111111111111111111111111111111", // System Program
"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", // Token Program
"JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4", // Jupiter v6
"675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8", // Raydium
]
Blockint Security Checks (from Daemon Blockint Tech)
- Flash loan detection: Flags accounts with near-equal large inflow/outflow (ratio threshold configurable, default 100x)
- High slippage: Flags effective slippage exceeding max bps (default 500 = 5%)
- Mint authority changes: Blocks token mint authority transfers
- Freeze authority changes: Blocks token freeze authority transfers
- Risk-labeled addresses: Blocks transactions involving known-risk addresses
Simulation Checks
NoErrorCheck: Transaction must simulate without errorsMaxUnitsCheck: Compute units must be under 1,400,000MaxBalanceDrainCheck: Total outflow must not exceed configured lamport limit
On-Chain Program Integration
Program ID: A29V5MUVs73y7XBHHxPpPcAW7h4gGHupbDdwYSwA2n9D
Instructions
| Instruction | Description |
|---|---|
initialize |
Initialize audit state (called once by authority) |
logAudit |
Record a decision (0=Allowed, 1=Blocked, 2=Pending) with simulation hash and reasoning |
registerAgent |
Register an agent identity with capability bitmask |
updateAgentReputation |
Adjust an agent's on-chain reputation score |
setPolicy |
Commit allowed programs, SOL cap, and rate limit on-chain |
emergencyPause |
Pause the protocol (circuit breaker) |
emergencyResume |
Resume the protocol |
stakeLamports |
Stake SOL for higher transaction limits (48h min before unstake) |
requestUnstake |
Start 7-day unstake cooldown |
claimUnstake |
Claim SOL after cooldown expires |
On-Chain Configuration
Bastion submits audit entries on-chain asynchronously (fire-and-forget). Enable with env vars:
BASTION_ON_CHAIN=1
SOLANA_RPC_URL=https://api.devnet.solana.com
BASTION_KEYPAIR_PATH=./keypair.json
When disabled (default), audit entries are local-only (Sled DB) and circuit breaker is API-only.
TypeScript SDK
import { BastionClient, BASTION_PROGRAM_ID } from "@zkos-labs/bastion-agentique";
import { Connection, Keypair } from "@solana/web3.js";
const client = new BastionClient({
connection: new Connection("https://api.devnet.solana.com")
});
const wallet = Keypair.generate();
// Register agent on-chain
await client.registerAgent(wallet, "MyTradingBot", 3);
// Set on-chain policy
const jupiterProgram = new PublicKey("JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4");
await client.setPolicy(wallet, [jupiterProgram], 5, 10);
// Fetch audit state
const state = await client.fetchAuditState();
// Emergency pause
await client.emergencyPause(wallet);
Understanding Audit Logs
Each log entry contains:
decision: ALLOWED, BLOCKED, or PENDING_APPROVALreason: Why it was blocked (policy violation, simulation error, blockint rule)block_id: UUID for use with/override(only for BLOCKED/PENDING_APPROVAL)intent: Human-readable description from the agenttransaction_id: Hash of the transaction payloadsignature: On-chain signature (populated after async on-chain submission)timestamp: Unix timestamp
Deployment
Docker (quick start)
docker-compose up --build
Manual
cargo build --release
HELIUS_API_KEY=your_key BASTION_ON_CHAIN=1 cargo run --release
On-chain program
cd programs/bastion-audit
anchor build
anchor deploy --provider.cluster devnet
MCP HTTP Server (SSE)
Start the MCP server for browser-native SSE access:
BASTION_SIDECAR_URL=https://bastion-agentique.fly.dev/ \
pnpm --filter @zkos-labs/mcp-server dev:http
Endpoints:
GET /mcp/sse- SSE connectionPOST /mcp/messages- MCP JSON-RPC messages (with?sessionId=<id>)GET /mcp/health- Health checkGET /mcp/pricing- Tool pricing + free tier info
15 tools (same as stdio MCP): simulate, ingest, get/update policy, audit logs/stats, override, pending, circuit breaker, cases, DID, token balances.
3 prompts: bastion_verify_transaction, bastion_security_review, bastion_incident_response.
Pricing
Bastion is an open-source community project, released under Apache 2.0. Read operations always free. Backend API calls optionally paid via USDT/USDC:
| Tool | Free/Month | Price (USD) |
|---|---|---|
bastion_simulate_transaction |
100 | $0.10 |
bastion_override_block |
10 | $1.00 |
bastion_update_policy |
5 | $5.00 |
bastion_circuit_breaker_toggle |
3 | $10.00 |
CORS
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Content-Type, Authorization, X-Api-Key, X-Agent-Id
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Related Skills
- blockchain-intelligence-playbook - Broader blockchain investigation methodology
- solana-onchain-intelligence-resources - Solana-specific tools and data sources
- defi-security-audit-agent - DeFi security patterns that complement Bastion policy rules
04 同仓库更多 Skills
bastion
Programmable Trust Runtime for Autonomous Systems. Orchestrates identity, policy, privacy, durable execution, and multi-chain settlement.
web2-api-firewall-administrator
Guides configuring Bastion Web2 API adapter policies for the Trust Runtime. Covers endpoint allowlists, provider budgets, rate limits, content inspection (PII/secrets detection), header filters, and OpenAPI spec-based auto-configuration. Use when configuring API call security for AI agents, setting provider spending caps, inspecting outbound API traffic, or setting up the Web2 adapter.
transaction-screening-workflow-concepts
Educational map of transaction-centric compliance screening-transfer as the atomic unit, deposit vs withdrawal direction, single and CSV import, transaction list and detail views, per-transfer screening, rescreen, and STR-style exports. Use when the user asks how monitoring UIs treat tx hashes, directions, or regulatory reporting hooks-not for legal filing advice or evading reporting.
solana-tracing-specialist
Guides Solana-specific on-chain forensics-ATA resolution, SPL instruction parsing, transaction history via RPC and indexers (e.g. Helius-style APIs), fund-flow graphs, Solana clustering heuristics, and program authority review. Use when the user investigates Solana wallets, SPL tokens, DEX/Jito flows, rug or phishing patterns on Solana, or needs evidence-structured tracing reports with public data only.
solana-onchain-intelligence-resources
Companion to blockint-skills Solana work-official doc indexes and stacks for RPC/indexers, sanctions and address intel MCP, web research, agent payments, graph UIs, Solana Foundation dev skills, Solana Policy Institute (policy/regulatory education), optional open-source Scrapy collection (BlockchainSpider), Impersonator Solana (dApp dev/testing), coral-xyz sealevel-attacks (security pattern examples), Neodyme Solana Security Workshop (workshop.neodyme.io), and Osec Solana auditor introduction blog (osec.io). Use when the user needs pointers to Helius, Range AI, Tavily, PayAI x402, React Flow, Solana.com skills, or SPI alongside on-chain forensics-not as a substitute for reading current provider docs, legal counsel, or API keys.
solana-defi-vulnerability-analyst-agent
Guides discovery and documentation of Solana DeFi protocol risks from public code and chain state-Anchor/native programs, PDAs, CPIs, oracles, pools, SPL mechanics, and historical tx reconstruction. Use when the user asks for Solana program security review, DeFi vulnerability triage, PDA or CPI safety, oracle or liquidity-pool risk, launchpad/bonding-curve issues, or evidence-backed severity findings without exploits or private keys.