WorkProof

WorkProof is an AI-verified freelance escrow application built on GenLayer. Clients define acceptance criteria and escrow GEN in an intelligent contract. Freelancers submit a public work URL, GenLayer validators evaluate the work, and the contract automatically releases payment when the submission passes.

The application has no backend server or database. The browser reads contract state directly, and every write is approved by the connected wallet.

Core Features

• On-chain GEN escrow for freelance jobs.
• Plain-English acceptance criteria stored with each job.
• Browser-wallet approval for every state-changing transaction.
• Public job board with status filters.
• Separate client and freelancer dashboard views.
• AI review of submitted public URLs.
• Validator consensus on the exact fetched evidence, pass/fail, and score range.
• Append-only on-chain evidence and prompt SHA-256 commitments.
• Strict review-result types and score bounds before settlement.
• Submission and payout deadline enforcement.
• Configurable revision limits from one to five attempts.
• Automatic 98% freelancer payout and 2% treasury fee.
• Client cancellation and refund before a job is accepted.
• Client escrow reclaim after an accepted job passes its deadline.
• GenLayer transaction appeals after revisions are exhausted.

How It Works

flowchart LR
    C[Client wallet] -->|Create job and escrow GEN| F[Next.js frontend]
    R[Freelancer wallet] -->|Accept and submit| F
    F -->|Signed transactions and reads| G[WorkProof contract]
    G -->|Fetch submitted URL| W[Public work]
    G --> V[GenLayer validators and LLMs]
    V -->|Consensus result| G
    G -->|98% on pass| R
    G -->|2% platform fee| T[Treasury wallet]
    G -->|Refund on cancel or expiry| C

Loading

1. A client connects MetaMask and creates a globally unique job ID.
2. The client supplies acceptance criteria, a future deadline, a revision limit, and a GEN payment.
3. The contract stores the job and holds the attached GEN in escrow.
4. A different wallet accepts the open job.
5. The assigned freelancer submits a public HTTP or HTTPS URL and notes.
6. Validators fetch the URL, hash the complete response, and place a bounded text slice in a versioned JSON review prompt.
7. Validators must agree on the exact evidence commitments before comparing the strict pass/fail result and score.
8. The contract rechecks the deadline and stores an append-only submission record before a passing review can release payment.
9. A failing review consumes one revision and returns the job to in_progress. When revisions reach zero, the job becomes disputed and the submission transaction can be appealed through GenLayer.

Review and Payment Rules

Rule	Value
Minimum passing score	70/100
Platform fee	2%
Freelancer payment	98%
Allowed revision limit	1-5
Validator score tolerance	10 points
Maximum fetched response	512,000 bytes
Maximum reviewed text	12,000 characters
Submission page size	50 records

Validators must independently produce identical source, reviewed-content, criteria, notes, and prompt commitments. They must also agree on pass/fail. Scores normally need to be within 10 points; very low scores are compared as a shared under-30 outcome.

The review result must contain exactly pass, score, met_criteria, unmet_criteria, and summary. pass must be a JSON boolean, score must be an integer from 0 through 100, and pass must equal score >= 70. The contract checks the deadline before evaluation and immediately before settlement.

If the submitted URL cannot be fetched, validators receive different content, the AI response is malformed, or the deadline gate fails, the transaction fails before a revision is consumed.

Job Lifecycle

Status	Meaning	Next actions
open	Payment is escrowed and no freelancer is assigned	Accept or client cancel
in_progress	A freelancer accepted the job	Submit work or client reclaim after deadline
completed	AI review passed	Freelancer and treasury are paid
disputed	All revisions were exhausted	Appeal the submission transaction
cancelled	Client cancelled before acceptance	Escrow returned to client
expired	Accepted job passed its deadline and was reclaimed	Escrow returned to client

An open job whose deadline has passed is displayed as expired by the frontend. Contract storage changes only through transactions, so the client can still cancel that on-chain open job to recover escrow.

Architecture

Intelligent Contract

contract/workproof.py is the complete application backend and settlement layer. It stores jobs and append-only submission records as JSON strings in separate TreeMap[str, str] collections, tracks IDs in a DynArray[str], and stores the platform treasury address supplied at deployment.

Public write methods:

• create_job
• accept_job
• submit_work
• cancel_job
• reclaim_expired_job

Public view methods:

• get_job
• get_submission
• list_submissions
• list_jobs
• list_jobs_by_status
• job_count

The contract pins its py-genlayer dependency in the source header and uses GenLayer non-deterministic web and LLM execution for work evaluation.

Frontend

The Next.js 15 and React 19 frontend:

• Connects to MetaMask through an EIP-1193 provider.
• Verifies and offers to add/switch the configured GenLayer network.
• Reads jobs directly from the contract.
• Sends writes directly from the connected wallet.
• Waits for GenLayer ACCEPTED status and checks for execution errors.
• Retries temporary read RPC failures.
• Displays the latest on-chain evidence and settlement commitments.
• Tracks the latest submission transaction in session storage for appeal instructions.

There is no API service, database migration, or server-side private key.

Repository Layout

.
|-- contract/
|   |-- workproof.py          # GenLayer intelligent contract
|   |-- deploy.mjs            # multi-network deployment script
|   |-- package.json
|   `-- .env.example
|-- frontend/
|   |-- src/app/
|   |   |-- page.tsx          # landing page
|   |   |-- jobs/page.tsx     # job board
|   |   |-- jobs/new/page.tsx # create and fund a job
|   |   |-- jobs/[id]/page.tsx
|   |   `-- dashboard/page.tsx
|   |-- src/lib/genlayer.ts   # contract reads, writes, and GEN helpers
|   |-- src/lib/useWallet.ts  # MetaMask and network hook
|   `-- src/components/
|-- tests/
|   |-- test_workproof.py
|   |-- test_workproof_security.py
|   |-- requirements.txt
|   `-- pytest.ini
`-- docs/
    |-- GENLAYER_BRADBURY_DEPLOY_HANDOFF.md
    `-- SETTLEMENT_SECURITY.md

Tech Stack

Layer	Technology
Intelligent contract	Python, GenLayer
Frontend	Next.js 15, React 19, TypeScript
Styling	Tailwind CSS
Wallet and contract SDK	MetaMask, genlayer-js
Contract tests	Standard-library unittest, Pytest, genlayer-test
Hosting	Vercel or any Next.js-compatible platform

Quick Start

Prerequisites

• Git
• Node.js 20 and npm
• MetaMask or another compatible browser wallet
• Bradbury testnet GEN for deployment, escrow, and transaction fees
• Python and Docker only when running the integration test suite

1. Clone the repository

git clone https://github.com/Jerry-Tekh/workproveApp.git
cd workproveApp

2. Deploy the contract

Install the deploy package:

cd contract
npm install

Create an ignored deployment environment file:

cp .env.example .env.local

Set:

PRIVATE_KEY=0xYOUR_DEPLOYER_PRIVATE_KEY
TREASURY_ADDRESS=0xYOUR_TREASURY_WALLET_ADDRESS

Deploy to Bradbury:

npm run deploy:testnet

The script waits for transaction acceptance, attempts to observe finalization, extracts the deployed address, and writes:

NEXT_PUBLIC_GENLAYER_NETWORK=testnet-bradbury
NEXT_PUBLIC_CONTRACT_ADDRESS=0xDEPLOYED_CONTRACT_ADDRESS

to frontend/.env.local.

The PRIVATE_KEY is used only by the deployment script. Normal application transactions are signed by each user in MetaMask.

3. Start the frontend

cd ../frontend
npm install
npm run dev

Open:

http://localhost:3000

If a contract is already deployed, skip step 2 and configure frontend/.env.local manually.

Environment Variables

Deployment: contract/.env.local

Variable	Required	Description
PRIVATE_KEY	Non-local deployments	Deployer wallet private key
TREASURY_ADDRESS	No	Receives the 2% fee; defaults to deployer

Never commit this file, paste the key into frontend configuration, or expose it through a NEXT_PUBLIC_* variable.

Frontend: frontend/.env.local

Variable	Required	Description
NEXT_PUBLIC_GENLAYER_NETWORK	Yes	SDK network key
NEXT_PUBLIC_CONTRACT_ADDRESS	Yes	Deployed WorkProof address

Supported network values:

• testnet-bradbury
• testnet-asimov
• studionet
• localnet

Both frontend values are public configuration and are embedded at build time. Restart the development server or redeploy after changing them.

Network Configuration

The browser wallet hook currently configures these networks:

Network key	Chain ID	RPC
testnet-bradbury	4221	https://rpc-bradbury.genlayer.com
testnet-asimov	4221	https://rpc-asimov.genlayer.com
studionet	61999	https://studio.genlayer.com/api
localnet	61127	http://localhost:4000/api

Bradbury and Asimov share the chain ID in the current frontend configuration. When switching between them, verify the active RPC in the wallet.

Contract Deployment

The deploy script supports:

cd contract
npm run deploy:localnet
npm run deploy:studionet
npm run deploy:testnet

The equivalent direct command is:

node deploy.mjs testnet-bradbury

For GenLayer Studio, deploy contract/workproof.py and enter the treasury wallet address in the treasury_address constructor field. It is the contract's single constructor argument.

To verify a new deployment, call:

job_count()

A new contract should return 0.

The hardened evidence schema requires a new deployment. Existing GenLayer contract storage is not changed by updating this repository, so deploy contract/workproof.py again and update NEXT_PUBLIC_CONTRACT_ADDRESS before submitting the revised project for review.

Using the Application

Client flow

1. Connect the wallet and switch to the configured network.
2. Open /jobs/new.
3. Enter a unique lowercase job ID.
4. Write acceptance criteria of at least 20 characters.
5. Set GEN payment, a future deadline, and revision limit.
6. Approve the escrow transaction in MetaMask.
7. Monitor the job from /dashboard.
8. Cancel while still open, or reclaim after an accepted job misses its deadline.

Freelancer flow

1. Connect a different wallet from the client.
2. Browse /jobs and accept an open job.
3. Complete the work and publish it at a validator-accessible URL.
4. Submit the URL and implementation notes.
5. Wait for validator consensus.
6. Resubmit after feedback when revisions remain.
7. If the job becomes disputed, appeal the submission transaction:

genlayer transactions appeal --tx 0xSUBMISSION_TRANSACTION_HASH

Testing

Run the dependency-free security suite without installing anything:

python3 scripts/verify_no_install.py

The script runs these checks individually:

python3 -m unittest tests/test_workproof_security.py -v
python3 -m py_compile contract/workproof.py tests/test_workproof_security.py

This suite covers strict verdict and score types, prompt boundaries, immutable evidence commitments, mutable URL disagreement, append-only records, malformed model output, deadline gates, and payout provenance.

The GenLayer integration suite additionally covers deployment, escrow, payout, fees, revisions, disputes, cancellation, pagination, duplicate IDs, deadline reclaim, malformed URLs, unreachable submissions, and provenance view methods.

Run against a local GenLayer environment:

python -m pip install -r tests/requirements.txt
genlayer up
python -m pytest tests/test_workproof.py -v

The test environment requires Docker. Contract deployment and normal frontend development do not require the Python test packages.

Build the frontend:

cd frontend
npm run build

Production Deployment

WorkProof only needs the frontend to be hosted after the contract is deployed.

Vercel

1. Import Jerry-Tekh/workproveApp.
2. Set the root directory to frontend.
3. Select the Next.js framework preset.
4. Add NEXT_PUBLIC_GENLAYER_NETWORK.
5. Add NEXT_PUBLIC_CONTRACT_ADDRESS.
6. Deploy.

Do not add PRIVATE_KEY or TREASURY_ADDRESS to Vercel. The treasury address is already stored in the deployed contract, and users sign their own transactions.

Any platform that supports a standard Next.js build can host the frontend:

npm run build
npm run start

Security Notes

• Keep deployment keys only in ignored local files or a dedicated secret manager.
• Use a dedicated deployment wallet rather than a primary personal wallet.
• Every client and freelancer write must be reviewed and approved in the connected wallet.
• Submitted work is untrusted public content. Acceptance criteria should be specific, measurable, and avoid relying on secrets or private resources.
• The work URL must be publicly reachable by validators and should not require authentication.
• Prefer content-addressed or version-pinned URLs. The on-chain SHA-256 commitments identify the exact reviewed bytes even if a normal URL changes later.
• GEN remains in the contract until completion, cancellation, or eligible deadline reclaim.
• Read the settlement security model before changing review or payout logic.

Known Limitations

• The project is configured for GenLayer test networks, not mainnet.
• WorkProof does not verify private repositories, authenticated pages, or local development URLs.
• There is no off-chain search index. The dashboard scans contract jobs and currently stops after 1,000 records.
• Appeals are performed with GenLayer tooling rather than an in-app appeal UI.
• Job IDs are globally unique within one contract deployment.
• A later submission can receive a different decision if its committed evidence changes or becomes unavailable.
• The contract accepts arbitrary HTTP/HTTPS work URLs; a production security review should define stricter URL and network-access controls.

Documentation

• GenLayer documentation
• GenLayer Studio
• Bradbury explorer
• WorkProof Bradbury handoff
• WorkProof settlement security
• WorkProof repository