가드레일이 적용된 온체인 Solana AI 에이전트 구축

블록체인 지갑과 상호작용하는 자율형 AI 에이전트는 엄청난 잠재력과 동시에 상당한 보안 위험을 동시에 나타냅니다. 엄격한 가드레일 (guardrails) 없이 LLM (Large Language Model)에 개인 키 (private keys)에 대한 직접적인 접근 권한을 부여하면 지갑 잔액이 고갈되거나 승인되지 않은 실행으로 빠르게 이어질 수 있습니다.

100 Days of Solana의 97일 차를 맞아, 저는 기본 거부 정책 엔진 (deny-by-default policy engine), 구조화된 도구 호출 (tool-calling) 루프, 그리고 전체 실행 로깅 (execution logging) 기능을 갖춘 프로덕션급 온체인 워크플로우 에이전트를 구축하고 문서화했습니다.

🛠️ 시스템 아키텍처 및 작동 원리

이 아키텍처는 엄격한 **정책 미들웨어 계층 (Policy Middleware Layer)**을 통해 에이전트의 의사 결정 계층 (LLM)과 실제 지갑 실행을 분리합니다:

1. 자율 의사 결정 엔진 (Autonomous Decision Engine): OpenRouter를 통한 LLM 도구 호출 루프를 사용하여 목표 상태(예: "저축 지갑에 최소 0.2 SOL이 있도록 보장하라")를 평가합니다.
2. 정책 집행 계층 (Policy Enforcement Layer): 모델이 요청한 모든 도구 호출이 블록체인에 도달하기 전에 가로챕니다.
   • 기본 거부 가드레일 (Deny-by-Default Guardrail): 안전 매개변수를 초과하는 모든 트랜잭션 요청은 자동으로 거부됩니다.
   • 한도 검증 (Limit Validation): 실행당 최대 전송 한도를 강제합니다.
   • 수신자 검증 (Recipient Verification): 알려진 화이트리스트 (white-listed) 계정 세트와 대조하여 목적지 주소를 검증합니다.
3. 구조화된 실행 로그 (Structured Run-Log): 모든 시스템 상태, 모델 입출력, 도구 페이로드 (payloads), 정책 승인/거부, 그리고 최종 실행 서명 (signatures)을 깔끔한 run-log.json 보고서에 기록합니다.

🚀 빠른 시작 및 설정 가이드

1. 사전 요구 사항

• Node.js (v18+)
• OpenRouter API Key (LLM 추론용)

2. 환경 설정

저장소를 클론하고 의존성을 설치하세요:

bash
npm install @solana/web3.js dotenv
export OPENROUTER_API_KEY="your-openrouter-key"

3. 키페어 (Keypair) 구성

운영 및 저축용 키페어를 생성하거나 로드하세요:

node setup-keys.mjs

이 과정을 통해 agent-wallet.json (운영 지갑)과 savings-wallet.json (저축 지갑)이 채워집니다.

💻 에이전트 워크플로우 실행 (Running the Agent Workflow)

Solana Devnet 또는 로컬 모의 환경 (local mock environment)에서 에이전트를 실행할 수 있습니다:

node agent-workflow.mjs

실행 출력 샘플 (Execution Output Sample):

GOAL: 저축 지갑(savings wallet)에 최소 0.2 SOL이 유지되도록 합니다. 자산을 이동하기 전에 잔액을 확인하고, 운영 지갑(operating wallet)에서 필요한 만큼만 이동하며, 최종 잔액을 검증합니다.

--- Turn 1 ---
...

🔒 정책 안전 계약 (Policy Safety Contract)

정책 엔진(policy engine)은 다음과 같은 명시적 규칙을 구현합니다:

function validatePolicy(action) {
  if (action.type === 'transfer_sol') {
    if (action.lamports > MAX_TRANSFER_LIMIT) {
...

📝 핵심 요약 (Key Takeaways)

1. Web3 쓰기 작업에 LLM 출력을 직접 신뢰하지 마세요: 항상 독립적이고 결정론적인(deterministic) 정책 검사기(policy checker)를 통해 트랜잭션을 실행해야 합니다.

2. 결정론적 폴백 (Deterministic Fallbacks): 로컬 모의 실행(local mock/dry-run) 기능을 포함하면 외부 RPC 속도 제한(rate limits)이나 네트워크 문제 발생 시에도 에이전트 파이프라인의 회복 탄력성(resilience)을 유지할 수 있습니다.

3. 감사 가능성 (Auditability): 완전한 구조화된 로깅 (run-log.json)을 통해 개발자는 실행 전후에 AI가 취한 모든 결정 경로를 검증할 수 있습니다.