AgentGuard

AgentGuard is a decentralized security and reputation scanner for blockchain agents. It helps users evaluate an agent address before interacting with it by combining public evidence, identity signals, malicious-behavior indicators, contract-risk information, and AgentGuard reputation data into a single security report.

The core decision is produced by a GenLayer Intelligent Contract rather than by the frontend. Multiple validators independently evaluate the available evidence and use GenLayer consensus to produce a canonical result that is persisted on-chain.

What AgentGuard Does

Given a blockchain agent address, AgentGuard can produce a security assessment covering:

• Identity verification — whether the available public information can be associated with the target agent.
• Legitimacy — whether the available evidence supports the claimed service or project.
• Malicious behavior — whether supplied evidence contains indicators of fraud, abuse, impersonation, malicious code, or other unsafe behavior.
• Contract risk — whether reliable contract-inspection information is available.
• Evidence quality — how much verifiable public evidence is available.
• AgentGuard reputation — registration and available reputation/dispute history for registered agents.
• Confidence — the confidence associated with the validator consensus.
• Risk decision — a canonical result such as LOW, MEDIUM, or HIGH, together with a user-facing decision such as SAFE, CAUTION, or BLOCK.

An important design principle is that unregistered does not automatically mean malicious. If an address is not registered, AgentGuard reports the missing reputation/history as unavailable rather than treating registration status itself as proof of bad behavior.

How It Works

User enters agent address
        |
        v
Optional website / GitHub evidence
        |
        v
Frontend submits scan_agent()
        |
        v
AgentGuard Intelligent Contract
        |
        +--> Gather available public evidence
        |
        +--> Evaluate identity and legitimacy
        |
        +--> Check malicious-behavior indicators
        |
        +--> Assess contract-risk information
        |
        +--> Include AgentGuard registration/reputation context
        |
        v
Multiple GenLayer validators evaluate independently
        |
        v
GenLayer consensus
        |
        v
Canonical security report
        |
        v
Persisted on GenLayer StudioNet
        |
        v
Frontend reads the canonical result

The frontend does not calculate the security score or make the final trust decision. It submits the scan request and displays the canonical result returned by the deployed AgentGuard contract.

Key Features

Address-only scanning

An agent does not have to be registered with AgentGuard before it can be scanned. This makes the scanner useful for discovering unknown agents rather than only checking agents that have already joined the reputation system.

When an address is unregistered and no additional evidence is supplied, the report clearly explains that reputation, identity, and legitimacy cannot be established from the available information.

Optional scan-time evidence

Users can provide a website and GitHub repository for an unregistered agent at scan time.

These URLs are used for that scan only. They do not create a registration record and do not permanently associate the address with the supplied profile.

Registered agents continue to use their stored profile information.

Validator consensus

The security assessment is evaluated by GenLayer validators. The contract uses the resulting consensus as the canonical decision rather than trusting a single model response.

The UI exposes the resulting consensus-backed report and evidence trail so users can understand why a decision was reached.

Persistent canonical results

Successful scans are persisted by the AgentGuard contract. The frontend subsequently reads the latest canonical scan from the contract instead of independently recreating the result.

Wallet-based submission

A browser wallet is required to submit a fresh scan transaction. The wallet connection is explicit:

1. The user clicks Connect Wallet.
2. The wallet requests permission once.
3. Refreshing the page attempts a silent eth_accounts restoration.
4. Account changes are detected automatically.
5. Disconnect clears the local connection state.

The scanner does not request wallet permissions every time the page is refreshed or every time a scan is submitted.

StudioNet network handling

The current frontend is configured for GenLayer StudioNet using studionet and chain ID 61999 (0xf22f). The scan path verifies the wallet network before submission and attempts to switch the wallet to StudioNet when necessary.

Architecture

Smart contract

The contract is located at:

contracts/AgentGuard.py

Important public methods include:

• scan_agent(address, website="", github_url="")
• get_agent(address)
• get_latest_scan(address)

The scan method accepts optional evidence URLs so an unregistered address can still be evaluated with useful public evidence.

Frontend

The frontend is located under:

frontend/

It is built with:

• Next.js 15
• React 19
• TypeScript
• Tailwind CSS
• genlayer-js 1.1.8

Important frontend components include:

frontend/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── globals.css
│   └── icon.svg
├── components/
│   ├── ScannerShell.tsx
│   ├── SecurityReport.tsx
│   └── EvidenceSection.tsx
└── lib/
    └── genlayer.ts

genlayer.ts contains the GenLayer client and scanner transaction flow. ScannerShell.tsx handles the wallet and scanner experience, while SecurityReport.tsx and EvidenceSection.tsx present the canonical security assessment and supporting evidence.

GenLayer Integration

AgentGuard uses GenLayer as the decision and consensus layer.

The frontend creates its GenLayer client against StudioNet:

createClient({ chain: studionet })

A fresh scan follows this general flow:

1. Validate the target address.
2. Validate and normalize optional evidence URLs.
3. Confirm that the browser wallet is connected.
4. Confirm the wallet is using StudioNet.
5. Call scan_agent(address, website, github_url).
6. Wait for the transaction to reach FINALIZED.
7. Re-read finalized transaction information when necessary.
8. Check explicit execution errors from GenLayer consensus data.
9. Read get_latest_scan(address).
10. Display the persisted canonical result.

This is important because a finalized transaction does not necessarily expose all execution details at the same top-level field in every genlayer-js response. The frontend therefore handles the StudioNet transaction structure defensively and only reports consensus failure when an explicit execution failure is present or a valid persisted scan cannot be obtained.

Security Report

A typical report contains:

• Decision
• Score
• Risk level
• Confidence
• AgentGuard registration status
• Identity verification result
• Malicious behavior result
• Contract risk
• Evidence quality
• Summary
• Agent address
• Website evidence
• GitHub evidence
• Reputation/dispute information
• Validator-derived evidence

For example, an unregistered agent with no supplied public evidence may receive a result similar to:

Decision: CAUTION
Score: 5 / 100
Risk: MEDIUM
Confidence: 25
Registration: UNREGISTERED
Identity: Not verified
Malicious behavior: Not detected
Contract risk: UNKNOWN

This means the scanner could not establish enough trustworthy evidence to recommend the agent, not that the address was proven malicious.

Evidence Model

AgentGuard deliberately distinguishes between:

• evidence that something is malicious,
• evidence that something is legitimate, and
• the absence of evidence.

For example:

No website supplied
        !=
Website proved malicious

and:

UNREGISTERED
        !=
Malicious

This distinction prevents the scanner from turning missing reputation or missing public information into unsupported accusations.

Storage Design

The contract uses GenLayer storage-compatible representations for persisted scan data.

Dynamic evidence is serialized deterministically as JSON text where necessary rather than relying on unsupported direct construction of generic storage objects in the pinned runtime.

The unregistered latest-scan mapping uses a string-to-string storage representation so the canonical scan can be safely serialized and persisted:

TreeMap[str, str]

The frontend decodes serialized evidence when presenting the report.

This design was chosen to remain compatible with the pinned GenLayer runtime while keeping the canonical result deterministic and readable.

Disputes

AgentGuard includes dispute-related contract logic. The scanner does not remove or bypass that logic when supporting unregistered scans.

For unregistered agents, the absence of AgentGuard history is explicitly represented as unavailable history. It is not presented as proof that the agent has never had disputes anywhere else.

Repository Structure

AgentGuard/
├── contracts/
│   └── AgentGuard.py
├── tests/
│   └── test_scoring.py
├── frontend/
│   ├── app/
│   ├── components/
│   ├── lib/
│   ├── package.json
│   ├── next.config.ts
│   ├── tailwind.config.ts
│   ├── tsconfig.json
│   └── .env.example
├── docs/
└── README.md

Requirements

Contract development

• Python 3.11+
• GenLayer CLI
• GenLayer-compatible Python environment
• The pinned GenLayer dependency used by the project

Frontend development

• Node.js
• npm
• A browser wallet such as MetaMask
• Access to GenLayer StudioNet

Installation

Clone the repository and enter the project:

git clone <YOUR_REPOSITORY_URL>
cd AgentGuard

Install frontend dependencies:

cd frontend
npm install

Create the local environment file:

cp .env.example .env.local

On Windows PowerShell, you can instead copy the example file with:

Copy-Item .env.example .env.local

Set the deployed contract address:

NEXT_PUBLIC_AGENTGUARD_ADDRESS=YOUR_AGENTGUARD_CONTRACT_ADDRESS

The current StudioNet deployment used during development is:

0x639EA365952a608a125f2089b68bc9e5069599B9

For a public repository, configure the deployment address through the environment file rather than hardcoding it in application code.

Running Locally

From frontend/:

npm run dev

The application will normally be available at:

http://localhost:3000

If another local process is using that port, Next.js may select another available port.

Production Build

Run:

npm run lint
npm run typecheck
npm run build

The project should pass all three checks before deployment.

Deployment

The frontend can be deployed to a Next.js-compatible hosting provider such as Vercel.

Configure the production environment variable:

NEXT_PUBLIC_AGENTGUARD_ADDRESS=0x639EA365952a608a125f2089b68bc9e5069599B9

The deployed frontend must use the same GenLayer network as the contract address. The current application targets StudioNet.

The contract itself must already be deployed to the target GenLayer network before the frontend can perform scans.

Wallet and Network Notes

The scanner requires a wallet for submitting scan_agent transactions.

The frontend intentionally separates:

• wallet permission,
• wallet account restoration,
• network verification, and
• transaction submission.

On refresh, the application uses a silent account lookup instead of requesting permissions again. Before scanning, the application verifies the wallet chain and attempts to move it to StudioNet.

If the wallet cannot switch to or add StudioNet, the scan cannot be submitted until the wallet is configured correctly.

Testing

Contract checks

The contract has been validated with GenLayer tooling and Python compilation checks.

Typical checks include:

genvm-lint lint contracts/AgentGuard.py
genvm-lint validate contracts/AgentGuard.py
genvm-lint typecheck contracts/AgentGuard.py
genvm-lint check contracts/AgentGuard.py
python -m py_compile contracts/AgentGuard.py
pytest -q

The current test suite contains coverage for registration, evidence, unregistered scans, URL handling, scoring, persistence, and regression cases around GenLayer storage compatibility.

Frontend checks

cd frontend
npm run lint
npm run typecheck
npm run build

Current Limitations

AgentGuard is designed to make evidence-based security assessments, not to guarantee that an agent is safe.

Important limitations include:

1. Public evidence availability — an address alone may provide insufficient information to verify identity or legitimacy.
2. Unregistered agents — reputation and dispute history are unavailable until an agent has an AgentGuard profile.
3. Contract inspection — a contract-risk value may remain UNKNOWN when reliable inspection data is unavailable.
4. Evidence quality — conclusions are limited by the quality and availability of public sources.
5. Consensus execution — GenLayer transactions require validator execution and consensus before a canonical result becomes available.
6. Wallet availability — a browser wallet is required for new scan transactions.
7. StudioNet — the current deployment is intended for development and demonstration use rather than production security guarantees.

Design Principles

1. The contract is the decision source

The frontend presents the canonical report. It does not independently calculate a trust score.

2. Missing evidence is not malicious evidence

AgentGuard distinguishes uncertainty from confirmed malicious behavior.

3. Registration is optional for discovery

Users can scan an unknown address without requiring the address owner to register first.

4. Evidence can be supplied without registration

A user can provide public website and GitHub sources for a one-time scan without creating a permanent AgentGuard profile.

5. Consensus matters

The security decision is produced through GenLayer validator evaluation and consensus rather than a single centralized application response.

6. Fail closed when evidence is insufficient

When important claims cannot be verified, the system reports uncertainty and lowers confidence rather than inventing positive evidence.

Example Use Cases

Checking an unknown agent before interaction

A user receives an agent wallet address from a marketplace or decentralized application. They enter the address into AgentGuard and review the resulting risk report before interacting with it.

Reviewing a registered agent

A registered agent can have a stored profile containing public evidence. AgentGuard can incorporate that profile and its reputation context into subsequent scans.

One-time verification of an unregistered project

A user can enter an address together with a website and GitHub repository. AgentGuard evaluates those sources for the scan without requiring the agent to register first.

Security operations

Teams can use the canonical report as an initial screening layer before allowing an agent to interact with a protocol, marketplace, treasury workflow, or automated service.

Status

The current working version supports:

• GenLayer StudioNet deployment
• Wallet connection and silent restoration
• StudioNet wallet verification
• Address-only scans
• Optional website evidence
• Optional GitHub evidence
• Registered and unregistered agent handling
• GenLayer validator consensus
• Canonical persisted scan results
• Security report and evidence trail
• Frontend validation and error handling
• Contract and frontend automated verification

License

Add the project's chosen open-source license here before publishing the repository. If you intend to accept external contributions, an OSI-approved license such as MIT or Apache-2.0 is a common choice.

Contributing

Contributions should preserve the core security model:

• Do not move score calculation into the frontend.
• Do not treat registration status as proof of malicious behavior.
• Keep consensus-derived decisions canonical.
• Keep evidence provenance visible.
• Validate and normalize external URLs before use.
• Preserve fail-closed behavior when critical evidence is unavailable.
• Run contract and frontend verification before submitting changes.

Acknowledgements

AgentGuard is built around GenLayer Intelligent Contracts and GenLayer's validator-based consensus model. The project uses genlayer-js for frontend interaction with the deployed Intelligent Contract.