Sentinel Protocol

Problem Statement

What is Sentinel Protocol?Sentinel Protocol is an AI-powered Web3 reputation and portfolio-protection system that continuously monitors users’ wallet crypto and market conditions, computes reputation scores for tokens, and autonomously proposes and (optionally) executes user-authorized protective actions (swaps). The goal is to protect long-term investors from sudden market shocks, manipulative events, or low-reputation tokens by combining: (1) real-time market feeds, (2) news and sentiment signals, (3) on-chain reputation data, (4) stochastic/randomness inputs for robustness, and (5) a human-or-policy-in-the-loop authorization step before any execution.Key design principles:Non-custodial control: users retain custody of funds; Sentinel suggests and executes actions only when explicitly authorized via secure delegated signing/authorization (e.g., Lit/Vincent).Modularity & auditability: functionality is separated into specialized agents (Price Feed, News, Reputation, Decision, Authorization, Executor). Each interaction is logged and traceable.Agent-to-Agent (A2A) orchestration: agents can query each other and form iterative proposals; decisions are made by a Decision Agent that aggregates evidence.Verifiability & unpredictability: Pyth Network’s real-time price feeds and entropy inputs are used for freshness, confidence, and verifiable randomness in stochastic reputation algorithms.Extensible & multi-network: designed to support multiple networks and data sources and to be extensible with new agents or policies.Why this project mattersTraditional portfolio protection tools are mostly centralized, manual, or rely on simple rule-based triggers. Sentinel aims to:bring AI-driven context (news + reputation + price) into protective decisions,make those decisions verifiable and auditable on-chain, andexecute them in a non-custodial, policy-driven manner so users retain control and minimize trust.Use cases include protecting a long-term ETH holder from a sudden collapse signaled by price shocks and reputation hits, or dynamically rebalancing exposure when news-driven risks spike.High-level architectureCore components (logical):Trigger mechanism — cron or event triggers (market anomaly detectors) POST to the orchestrator endpoint.Next.js orchestrator — API route receives trigger and streams progress to frontend via SSE or pushes updates to queues / WebSockets. It orchestrates agent execution, retries, and aggregates results.Agents — independent modules/services:Price Feed Agent: queries Pyth on-chain feeds + Coingecko for fallback/off-chain context, computes volatility, staleness checks, confidence intervals.News Feed Agent: pulls relevant news (NewsAPI, RSS, social signals), performs extraction, and scores sentiment/relevance.Reputation Agent: computes token reputation from on-chain data (Hedera sidechain storage / contracts), historical behavior, and other heuristics.Decision Agent: aggregates signals, reasons over them (optionally uses LLMs/LLM-assisted policies), proposes an action with rationale and risk estimates.Authorization Agent: checks user-configured policies (limits, allowed tokens, rate caps), or requests user-signed authorization through Lit/Vincent.Execution Agent: executes approved actions by interacting with decentralized execution providers (e.g., Vincent/Lit or DEX APIs), logging execution traces.Storage & records — a small database (Postgres or similar) for storing audits, proposals, logs, and reputations; optionally Hedera sidechain for finalized reputation publications.Frontend — a Next.js UI that connects to SSE or WebSocket to show progressive logs, decisions, and request confirmations from the user.Data flows:Trigger → orchestrator → run agents in sequence/parallel → DecisionAgent proposes action → AuthorizationAgent validates → ExecutionAgent executes (if authorized) → logs & receipts stored and optionally published on Hedera.Agents and their responsibilities (detailed) Price Feed AgentSources: Pyth network (primary on-chain), Coingecko (off-chain), fallbacks like other oracles when needed.Responsibilities: fetch latest prices and timestamps, compute volatility (e.g., historical standard deviation, realized volatility), evaluate confidence/staleness, and normalize unit conversions.Outputs: structured price objects, volatility metrics, staleness flags, and confidence scores.News Feed AgentSources: NewsAPI, curated RSS, on-chain mentions, and optionally social sources.Responsibilities: fetch recent articles related to tokens in portfolio, deduplicate, extract titles and short summaries, compute sentiment and relevance, surface top-n items.Outputs: categorized news lists and sentiment scores per token.Reputation AgentSources: Hedera-based reputation store (sidechain or contract), historical on-chain actions, known exploit lists, and derived heuristics (e.g., owner concentration).Responsibilities: compute a composite reputation score (market stability, fundamental indicators, prior malicious signals). Uses verifiable entropy from Pyth when randomness is required for stochastic steps.Outputs: per-token reputation object (score, rationale, contributing factors).Decision AgentRole: the central reasoning agent that synthesizes price, news, reputation, and portfolio constraints to propose an action.Behavior: can request up to a bounded number of A2A queries to other agents, aggregate evidence, and generate a ranked set of proposed actions with expected benefits & risks.Optionally uses LLM summarization or rule-based heuristics (LangChain + OpenAI for reasoning, with deterministic seeds and low temperature).Authorization AgentValidates proposals against user policies (max swap %, allowed tokens, max daily txs).If policy requires user consent, it prepares an authorization request that the user can sign via Lit/Vincent or declines.Returns structured approval or rejection with reasons.Execution AgentExecutes approved actions through a secure, auditable path — either submitting transactions to DEXs or invoking a delegated actor using Vincent (Lit).Ensures transaction receipts and execution logs are recorded.Protocol-level standards (A2A)Sentinel follows an Agent-to-Agent (A2A) messaging standard: standardized envelopes containing id, timestamp, sender, receiver, intent, data, context, and trace fields. This ensures:traceability (correlation IDs and spans),reproducibility (deterministic context where required),clear auditing (every agent message is logged),safe retries and idempotence patterns.An orchestration attempt is a finite series of A2A messages: DecisionAgent requests data → other agents respond → DecisionAgent proposes → AuthorizationAgent evaluates → DecisionAgent revises (if necessary) — repeat up to N times.Security, trust, and non-custodial executionNon-custodial design: Sentinel never holds user keys. Authorization and signatures are handled by the user (or via Lit’s delegated authorization where the user’s policy is cryptographically enforced).Authorization flow: proposals are signed/authorized using Lit (Vincent) or by the user directly. AuthorizationAgent enforces policy and logs decisions before execution.Auditing & transparency: all proposals, agent inputs, authorization decisions, and execution receipts are stored and optionally anchored (hash) to Hedera for tamper-evidence.Threat model & mitigations:Compromised agent: agents run with least privilege and outputs are sanity-checked by Decision & Authorization agents.Oracle manipulation: use on-chain Pyth feeds with confidence bounds; cross-check with off-chain sources.Malicious LLM answer: AuthorizationAgent enforces strict policy bounds; DecisionAgent provides rationale and confidence metrics.Stochastic reputation model & entropyReputation scoring uses deterministic computations augmented by verifiable randomness (Pyth Entropy) to reduce predictability in score calculation and reduce exploitability.Entropy is incorporated in small controlled ways: e.g., to randomize tie-breakers or to select samples for bootstrapped stability computations. Every use of entropy is recorded and reproducible from the on-chain entropy source.Frontend & real-time UXThe Next.js frontend uses Server-Sent Events (SSE) for streaming agent logs and decisions in real time. SSE is light-weight, reliable, and well-suited for one-way progress updates.UX shows progressive steps: fetching price → fetching news → reputation check → proposed action → authorization state → execution result.Messages are formatted (markdown via react-markdown), summarized (via LLM or deterministic summarizer), and displayed in an audit-friendly way.Users can set policies, view rationale, and approve/decline actions. The UI also supports a “simulation mode” for dry run rebalances.Developer ergonomics & project layoutMonorepo approach recommended: packages/ai (agents, langchain code) and packages/frontend (Next.js). This eases local development and reuse.Agent interfaces are standardized (e.g., getPrice(query), getNews(query), assessReputation(query), proposeAction(context, portfolio)).A2A message utilities (create message envelope, logging, correlation) are provided to all agents.Use jsconfig/tsconfig path aliases to keep imports clean (e.g., @ai/*).Sample files: orchestrator route (app/api/agent/orchestrate/route.js), agent modules in ai/agents/, SSE streaming utilities, and helper formatProposedActionMessage.Deployment, scaling, and operationsLocal dev: npm install in each package or via workspace; npm run dev for Next.js.Production: Serve Next.js on a serverful environment (or Vercel with scheduled function integration for cron). For streaming SSE and persistent orchestration, prefer a serverful host (e.g., AWS/GCP/Render) or edge functions with streaming support.Scaling: Move heavy or long-running agent tasks to worker processes or job queues (BullMQ, Redis). Keep orchestrator as coordinator; workers fetch data and compute heavy reputation models asynchronously.Monitoring & observability: Structured logs (JSON), request tracing, Prometheus metrics for agent latencies, Sentry for errors.Cost considerations: LLM calls, external API usage, and on-chain transactions are main cost drivers. Use batching and caching where possible, and offload repeated expensive computations to scheduled jobs.Evaluation, testing, and validationUnit tests for each agent, mocking external APIs (Pyth, NewsAPI, Coingecko).Integration tests for the orchestrator: simulate portfolio scenarios and assert that decisions follow expected policies.Backtesting: run agents and DecisionAgent over historical market data to compute expected outcomes and verify the decision heuristics.Security reviews: third-party audit for Authorization/Executor flows and Hedera integration before any live execution.Limiters, blockers & open researchCurrent blockers and research needs:Finalizing the architecture for the reputation sidechain: how to store/retrieve reputations, publish cadence, and consensus rules.Designing robust, secure, non-custodial delegated execution using Lit/Vincent at scale.Formalizing reputation scoring methodology and calibrating stochastic parameters (entropy use) to make scores resistant to manipulation.Compliance & privacy: handling identity-linked data or regional regulatory constraints.Governance and ethicsUser policies: users should be able to define conservative or aggressive policies (e.g., “never swap more than X%”).Human oversight: default mode is user-authorization; automated execution is allowed only where user has set explicit non-interactive policies.Fairness & manipulation resistance: by combining multiple data sources, verifiable randomness, and hedging rules, the system aims to minimize susceptibility to coordinated manipulation.

Solution

Core architecture and technologiesSentinel Protocol is built as a modular, non-custodial Web3 system, combining AI reasoning, real-time market intelligence, and on-chain reputation management. The project is primarily implemented as a monorepo with two main packages:packages/ai – Houses the intelligent agent modules and orchestration logic.packages/frontend – A Next.js-based UI for monitoring, approval, and real-time progress streaming.The system is designed around a micro-agent architecture, where each agent (Price Feed, News Feed, Reputation, Decision, Authorization, Execution) is a separate service/module. Agents communicate via a standardized Agent-to-Agent (A2A) protocol, which ensures traceability, reproducibility, and deterministic orchestration of decisions.Technologies and frameworksWeb3 & blockchain integration:Pyth Network for on-chain real-time price feeds with confidence intervals.Hedera Hashgraph for sidechain reputation storage and verifiable anchoring of scores.DEX APIs / Lit / Vincent for secure, non-custodial execution of trades and swaps.Backend orchestration:Next.js API routes act as the orchestrator endpoints. Triggers (cron jobs, market anomaly detectors, or webhooks) POST events here.Javascript for modular agent development and typed interfaces.AI & reasoning:LangChain combined with deterministic LLM prompts (OpenAI or local LLM) for Decision Agent reasoning and summarization.Data analysis and text extraction using prebuilt NLP libraries for the News Feed Agent.Stochastic reputation calculations augmented with Pyth-provided entropy for unpredictability and anti-manipulation robustness.Frontend:Next.js + React for real-time UX.Server-Sent Events (SSE) to stream agent logs and decision steps progressively.react-markdown for audit-friendly rendering of agent messages.UI supports dry-run simulations, policy configuration, and on-chain reputation visualization.How components are pieced togetherTrigger → Orchestrator → Agents: Cron jobs or anomaly detectors call the orchestrator API route. The orchestrator then invokes relevant agents sequentially or in parallel.Agent-to-Agent messaging: Decision Agent queries Price, News, and Reputation agents using A2A envelopes. Each envelope contains metadata, context, and correlation IDs for auditability.The Hedera Agent Kit x A2A Agent Orchestration Architecture automates on-chain decision-making by coordinating multiple AI agents through a Next.js backend and the Google A2A protocol. When triggered—either periodically by a cronjob or by sudden market changes—the orchestrator endpoint gathers the trigger reason and user portfolio before cueing agents to act. The Price Feed Agent retrieves on-chain price data from Pyth and off-chain price data from Coingecko as a fallback; while the News Feed Agent collects relevant market news, and the Reputation Agent computes on-chain reputation metrics. The coin's reputation information is computed using a stochastic pricing model on the Hedera chain and Pyth's entropy functions, on demand. The smart contract deployed on Hedera, keeps a track of many coins in the market, as well as their reputation information. The Decision Agent aggregates these insights to propose an optimal action, such as a token swap, stake, unstake, or no action. This proposal is then validated by the Authorization Agent, ensuring it aligns with user-defined constraints. If approved, the Executor Agent executes the action through Vincent (Lit Protocol); otherwise, the system revises and retries, ensuring safe, informed, and autonomous execution of on-chain strategies, as per user-defined settings obtained from Vincent. While retrying, the Decision Agent can communicate A2A with the other Data Source Agents, and fetch the requisite information.Decision → Authorization → Execution: Decision Agent proposes actions; Authorization Agent evaluates them against user policies. If approved, Execution Agent submits the transaction to the blockchain or DEX.Logging & auditing: Every message, decision, and transaction receipt is logged in PostgreSQL and optionally anchored to Hedera.Partner technologies and integration benefitsPyth Network: Provides reliable, verifiable price feeds with confidence metrics, reducing risk of oracle manipulation.Hedera: Enables tamper-evident reputation storage and decentralized verification.Lit / Vincent: Allows non-custodial delegated execution, making automated portfolio actions safe and auditable.Coingecko / NewsAPI: Supplement on-chain feeds with off-chain context for more robust reputation and risk evaluation.Notable hacks and clever solutionsStochastic reputation model: Integrated verifiable on-chain entropy to break predictability and prevent attackers from gaming reputation scores.Agent orchestration retries: Orchestrator can rerun or revise agent proposals deterministically if any agent fails or returns conflicting data.Real-time streaming UX: Lightweight SSE implementation streams logs from backend agents progressively without requiring full WebSocket infrastructure.Dry-run mode: Allows users to simulate portfolio actions, including swaps and rebalances, using live market and reputation data, without risking funds.Multi-source fallback system: Price Feed Agent automatically falls back to off-chain or alternative oracle data if primary feeds are stale or unavailable.SummarySentinel Protocol combines AI-driven reasoning, non-custodial execution, and multi-source verification into a modular system. The project is a hybrid of Web3 infrastructure, deterministic/stochastic AI models, and secure execution mechanisms. By carefully separating agents, using verifiable randomness, and enabling user-controlled authorization, Sentinel achieves both robust portfolio protection and transparent auditability.