AGENT SKILL

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
所属仓库
zkos-labs/bastion
最近更新
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

  1. Start Bastion server (see README)
  2. Register your agent identity via POST /agents (NEW in v0.3.0)
  3. Configure policy (whitelist programs, set SOL caps, enable blockint checks)
  4. Send transactions to POST /simulate before signing
  5. If allowed, sign and send the transaction
  6. If blocked, request human override via POST /override
  7. 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 calls emergencyPause on-chain if configured)
  • POST /circuit-breaker/disengage - Resumes (calls emergencyResume on-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 errors
  • MaxUnitsCheck: Compute units must be under 1,400,000
  • MaxBalanceDrainCheck: 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_APPROVAL
  • reason: 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 agent
  • transaction_id: Hash of the transaction payload
  • signature: 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 connection
  • POST /mcp/messages - MCP JSON-RPC messages (with ?sessionId=<id>)
  • GET /mcp/health - Health check
  • GET /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

zkos-labs
zkos-labs/bastion

bastion

Programmable Trust Runtime for Autonomous Systems. Orchestrates identity, policy, privacy, durable execution, and multi-chain settlement.

★ 3
zkos-labs
zkos-labs/bastion

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.

★ 3
zkos-labs
zkos-labs/bastion

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.

★ 3
zkos-labs
zkos-labs/bastion

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.

★ 3
zkos-labs
zkos-labs/bastion

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.

★ 3
zkos-labs
zkos-labs/bastion

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.

★ 3