Subjective Event Resolver on GenLayer

A beginner-friendly GenLayer tutorial project that shows how an Intelligent Contract can help resolve subjective, real-world cases.

This demo lets a user submit a case such as "Does this submission meet the checklist?" or "Was this task completed successfully?" The GenLayer contract stores the case, asks for an AI-assisted resolution through GenLayer's equivalence principle, and exposes the final status, decision, and rationale to a small frontend.

Why This Fits GenLayer

Traditional smart contracts are great when the rules are fully deterministic: transfer tokens, compare numbers, check signatures, or enforce exact state transitions. They are less natural for human judgment problems where the answer depends on text, evidence, criteria, or context.

GenLayer is designed for Intelligent Contracts: Python contracts that can combine blockchain state with web data, natural language reasoning, and validator consensus for non-deterministic work. This project keeps that idea small and practical by resolving one subjective case at a time.

Demo Flow

1. Open the frontend.
2. Fill in a case title, description, optional checklist, and optional evidence.
3. Submit the case to store it.
4. Resolve the case.
5. Review the status, decision, and rationale.

The frontend starts in local demo mode so newcomers can explore the UX immediately. Once a GenLayer localnet or Studio deployment is ready, switch to GenLayer mode and provide the deployed contract address.

Tech Stack

• Python Intelligent Contract in contracts/SubjectiveEventResolver.py
• GenLayer contract patterns from the current docs
• React + Vite + TypeScript frontend
• genlayer-js for frontend-to-contract calls
• genlayer-test / gltest configuration for local contract testing

Prerequisites

• Python 3.12+
• Node.js 18+
• npm 7+
• Docker 26+ only if you want to run GenLayer Studio locally

Installation

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cd frontend
npm install
cp .env.example .env

Running Locally

1. Run the frontend in demo mode

cd frontend
npm run dev

Open the URL printed by Vite. Demo mode uses a local mock resolver and does not require a blockchain node.

2. Run with GenLayer localnet or Studio

Start a GenLayer-compatible endpoint. The current GenLayer docs describe two practical local options:

glsim --port 4000 --validators 5

or, for local Studio:

npm install -g genlayer
genlayer init
genlayer up

Deploy contracts/SubjectiveEventResolver.py using your preferred GenLayer workflow, then update frontend/.env:

VITE_DEMO_MODE=false
VITE_GENLAYER_RPC_URL=http://127.0.0.1:4000/api
VITE_GENLAYER_CONTRACT_ADDRESS=0xYourDeployedContractAddress

Restart the frontend after editing .env.

How the Intelligent Contract Works

The contract stores one current case:

• title
• description
• criteria
• evidence
• status
• decision
• rationale

submit_case(...) validates and stores the case. resolve_case() builds a plain-language input from the case and uses:

gl.eq_principle.prompt_non_comparative(...)

That pattern asks the leader to produce an answer and asks validators to judge whether the answer satisfies the provided criteria. In this demo, the answer must choose APPROVED or REJECTED and provide a short rationale.

How the Frontend Works

The frontend has two resolver clients:

• Demo mode: local mock logic in frontend/src/services/mockResolver.ts
• GenLayer mode: genlayer-js calls in frontend/src/services/genlayerResolver.ts

The UI reads and writes the same simple contract methods in GenLayer mode:

• submit_case(title, description, criteria, evidence)
• resolve_case()
• get_case_count()
• get_case_title()
• get_case_description()
• get_case_criteria()
• get_case_evidence()
• get_status()
• get_decision()
• get_rationale()

Folder Structure

.
├── contracts/
│   └── SubjectiveEventResolver.py
├── docs/
│   ├── cheatsheet.md
│   ├── demo-script.md
│   ├── submission-summary.md
│   └── tutorial.md
├── frontend/
│   └── src/
├── tests/
│   └── direct/
├── gltest.config.yaml
├── requirements.txt
└── README.md

Troubleshooting

The frontend says the contract address is missing.
Set VITE_GENLAYER_CONTRACT_ADDRESS in frontend/.env, then restart npm run dev.

The frontend works in Demo mode but not GenLayer mode.
Confirm your RPC endpoint is running at VITE_GENLAYER_RPC_URL and that the contract address matches the deployed SubjectiveEventResolver.py.

Transactions take longer than expected.
GenLayer write calls go through transaction processing and consensus. Use Demo mode for UI exploration and localnet/Studio for real contract testing.

Python tooling fails to install.
Confirm you are using Python 3.12 or newer.

Next Steps and Extensions

• Store multiple cases instead of one latest case.
• Add a web evidence fetch step with gl.nondet.web.get.
• Add stricter JSON output parsing for the resolution.
• Add deployment scripts once your target GenLayer environment is selected.
• Record a short demo using docs/demo-script.md.

Documentation Honesty

This repository follows the current public GenLayer docs for contract shape, genlayer-js, and equivalence principle usage. Full end-to-end consensus behavior must be validated in your chosen GenLayer runtime, such as GLSim, local Studio, hosted Studio, or testnet.