feat: add FreelancerDisputeResolver intelligent contract example

.env.example

@@ -0,0 +1,4 @@
+# Freelancer Dispute Resolver
+CONTRACT_ADDRESS=
+FREELANCER_ADDRESS=
+JOB_DESCRIPTION=

contracts/freelancer_dispute_resolver.py

@@ -0,0 +1,156 @@
+# { "Depends": "py-genlayer:test" }
+from genlayer import *
+import json
+
+class FreelancerDisputeResolver(gl.Contract):
+    job_description: str
+    deliverables_url: str
+    client: Address
+    freelancer: Address
+    client_evidence: str
+    freelancer_evidence: str
+    dispute_raised: bool
+    resolved: bool
+    verdict: str
+    verdict_reasoning: str
+
+    def __init__(self, freelancer_address: str, job_description: str) -> None:
+        self.client = gl.message.sender_account
+        self.freelancer = Address(freelancer_address)
+        self.job_description = job_description
+        self.deliverables_url = ""
+        self.client_evidence = ""
+        self.freelancer_evidence = ""
+        self.dispute_raised = False
+        self.resolved = False
+        self.verdict = ""
+        self.verdict_reasoning = ""
+
+    @gl.public.write
+    def submit_deliverables(self, deliverables_url: str) -> None:
+        if gl.message.sender_account != self.freelancer:
+            raise Exception("Only the freelancer can submit deliverables.")
+        if self.resolved:
+            raise Exception("This contract has already been resolved.")
+        self.deliverables_url = deliverables_url
+
+    @gl.public.write
+    def raise_dispute(self, evidence: str) -> None:
+        if self.resolved:
+            raise Exception("This contract has already been resolved.")
+        if not self.deliverables_url:
+            raise Exception("Freelancer must submit deliverables before a dispute can be raised.")
+        sender = gl.message.sender_account
+        if sender == self.client:
+            if self.client_evidence:
+                raise Exception("Client has already submitted evidence.")
+            self.client_evidence = evidence
+        elif sender == self.freelancer:
+            if self.freelancer_evidence:
+                raise Exception("Freelancer has already submitted evidence.")
+            self.freelancer_evidence = evidence
+        else:
+            raise Exception("Only the client or freelancer can submit evidence.")
+        self.dispute_raised = True
+
+    @gl.public.write
+    def resolve_dispute(self) -> None:
+        if not self.dispute_raised:
+            raise Exception("No dispute has been raised yet.")
+        if self.resolved:
+            raise Exception("Dispute has already been resolved.")
+        if not self.client_evidence:
+            raise Exception("Client has not submitted evidence yet.")
+        if not self.freelancer_evidence:
+            raise Exception("Freelancer has not submitted evidence yet.")
+
+        deliverables_url = self.deliverables_url
+        job_description = self.job_description
+        client_evidence = self.client_evidence
+        freelancer_evidence = self.freelancer_evidence
+
+        def fetch_deliverables() -> str:
+            return gl.nondet.web.get(deliverables_url, mode="text")
+
+        deliverables_content = gl.eq_principle.strict_eq(fetch_deliverables)
+
+        prompt = f"""
+You are an impartial and expert freelance arbitrator. Your job is to fairly resolve
+a dispute between a client and a freelancer based solely on the evidence provided.
+
+JOB DESCRIPTION:
+{job_description}
+
+DELIVERABLES (fetched from submitted URL):
+{deliverables_content[:3000]}
+
+CLIENT'S EVIDENCE / COMPLAINT:
+{client_evidence}
+
+FREELANCER'S EVIDENCE / REBUTTAL:
+{freelancer_evidence}
+
+INSTRUCTIONS:
+Carefully review all of the above. Then decide:
+  - "freelancer" if the work sufficiently meets the job description and the client's complaint is not substantiated.
+  - "client" if the work clearly does NOT meet the job description and the client's complaint is valid.
+  - "draw" if the evidence is ambiguous or both parties share fault equally.
+
+Respond ONLY in the following JSON format, nothing else:
+{{
+  "verdict": "freelancer" | "client" | "draw",
+  "reasoning": "<2-4 sentences explaining the decision impartially>"
+}}
+Do not include any text outside the JSON object. Do not use markdown code fences.
+"""
+
+        def run_arbitration() -> str:
+            result = gl.nondet.exec_prompt(prompt)
+            result = result.replace("```json", "").replace("```", "").strip()
+            return result
+
+        raw_verdict = gl.eq_principle.prompt_comparative(
+            run_arbitration,
+            """The 'verdict' field must be one of: 'freelancer', 'client', or 'draw'.
+The 'reasoning' must logically support the verdict based on the job description
+and the evidence provided. Minor wording differences in 'reasoning' are acceptable.""",
+        )
+
+        try:
+            parsed = json.loads(raw_verdict)
+        except json.JSONDecodeError as err:
+            raise Exception(f"Arbitration returned invalid JSON: {raw_verdict[:200]}") from err
+
+        verdict = parsed.get("verdict", "")
+        reasoning = parsed.get("reasoning", "")
+
+        if verdict not in ("freelancer", "client", "draw"):
+            raise Exception(f"Invalid verdict '{verdict}'. Must be 'freelancer', 'client', or 'draw'.")
+
+        self.verdict = verdict
+        self.verdict_reasoning = reasoning
+        self.resolved = True
+
+    @gl.public.view
+    def get_job_info(self) -> dict:
+        return {
+            "job_description": self.job_description,
+            "deliverables_url": self.deliverables_url,
+            "client": self.client.as_hex,
+            "freelancer": self.freelancer.as_hex,
+        }
+
+    @gl.public.view
+    def get_dispute_status(self) -> dict:
+        return {
+            "dispute_raised": self.dispute_raised,
+            "client_evidence": self.client_evidence,
+            "freelancer_evidence": self.freelancer_evidence,
+            "resolved": self.resolved,
+            "verdict": self.verdict,
+            "verdict_reasoning": self.verdict_reasoning,
+        }
+
+    @gl.public.view
+    def get_verdict(self) -> str:
+        return self.verdict

deploy/deployScript.freelancer.ts

@@ -0,0 +1,48 @@
+import { deployContract } from "@genlayer/cli";
+import * as path from "path";
+import * as dotenv from "dotenv";
+
+dotenv.config();
+
+const FREELANCER_ADDRESS: string =
+  process.env.FREELANCER_ADDRESS ||
+  (() => {
+    throw new Error("FREELANCER_ADDRESS is required. Set it in your .env file.");
+  })();
+
+const JOB_DESCRIPTION: string =
+  process.env.JOB_DESCRIPTION ||
+  "Build a Python web scraper that collects product names and prices " +
+  "from an e-commerce site and outputs them as a CSV file. " +
+  "The code must be well-documented, include error handling, and be hosted " +
+  "in a public GitHub repository with a clear README.";
+
+async function main() {
+  console.log("🚀 Deploying FreelancerDisputeResolver...");
+  console.log(`   Freelancer address : ${FREELANCER_ADDRESS}`);
+  console.log(`   Job description    : ${JOB_DESCRIPTION.length > 80 ? JOB_DESCRIPTION.slice(0, 80) + "..." : JOB_DESCRIPTION}`);
+
+  const contractPath = path.resolve(
+    __dirname,
+    "../contracts/freelancer_dispute_resolver.py"
+  );
+
+  const contractAddress = await deployContract({
+    contractFilePath: contractPath,
+    args: [FREELANCER_ADDRESS, JOB_DESCRIPTION],
+  });
+
+  console.log("\n✅ Contract deployed successfully!");
+  console.log(`   Contract address: ${contractAddress}`);
+  console.log(
+    "\n📋 Next steps:\n" +
+    "   1. Copy the contract address above.\n" +
+    "   2. Add it to your .env as CONTRACT_ADDRESS=<address>\n" +
+    "   3. Open GenLayer Studio and interact via Write/Read Methods."
+  );
+}
+
+main().catch((err) => {
+  console.error("❌ Deployment failed:", err);
+  process.exit(1);
+});

test/test_freelancer_dispute_resolver.py

@@ -0,0 +1,170 @@
+import pytest
+import os
+
+STUDIO_URL = os.getenv("GENLAYER_STUDIO_URL", "http://localhost:8080")
+
+JOB_DESCRIPTION = (
+    "Build a Python web scraper that collects product names and prices from "
+    "an e-commerce site and outputs them as a CSV file. "
+    "The code must be well-documented, include error handling, and be hosted "
+    "in a public GitHub repository with a clear README."
+)
+
+TEST_DELIVERABLES_URL = "https://github.com/genlayerlabs/genlayer-studio"
+
+
+@pytest.fixture(scope="module")
+def setup():
+    from genlayer_py.testing import GenLayerTestClient
+    client = GenLayerTestClient(studio_url=STUDIO_URL)
+    accounts = client.get_accounts()
+
+    # GenLayer Studio must have at least 3 accounts (client, freelancer, third party)
+    assert len(accounts) >= 3, "GenLayer Studio must have at least 3 accounts configured."
+
+    client_account = accounts[0]
+    freelancer_account = accounts[1]
+    third_party_account = accounts[2]
+
+    contract_address = client.deploy_contract(
+        sender=client_account,
+        contract_file="contracts/freelancer_dispute_resolver.py",
+        args=[freelancer_account["address"], JOB_DESCRIPTION],
+    )
+
+    return {
+        "client": client,
+        "contract_address": contract_address,
+        "client_account": client_account,
+        "freelancer_account": freelancer_account,
+        "third_party_account": third_party_account,
+    }
+
+
+# ── Happy path tests (must run in order) ─────────────────────────────────────
+
+@pytest.mark.order(1)
+def test_initial_state(setup):
+    result = setup["client"].call_contract(
+        sender=setup["client_account"],
+        contract_address=setup["contract_address"],
+        function="get_job_info",
+        args=[],
+    )
+    assert result["job_description"] == JOB_DESCRIPTION
+    assert result["deliverables_url"] == ""
+
+
+@pytest.mark.order(2)
+def test_freelancer_submits_deliverables(setup):
+    setup["client"].send_transaction(
+        sender=setup["freelancer_account"],
+        contract_address=setup["contract_address"],
+        function="submit_deliverables",
+        args=[TEST_DELIVERABLES_URL],
+    )
+    result = setup["client"].call_contract(
+        sender=setup["client_account"],
+        contract_address=setup["contract_address"],
+        function="get_job_info",
+        args=[],
+    )
+    assert result["deliverables_url"] == TEST_DELIVERABLES_URL
+
+
+@pytest.mark.order(3)
+def test_client_raises_dispute(setup):
+    setup["client"].send_transaction(
+        sender=setup["client_account"],
+        contract_address=setup["contract_address"],
+        function="raise_dispute",
+        args=["The README is missing and there is no CSV output as specified."],
+    )
+    result = setup["client"].call_contract(
+        sender=setup["client_account"],
+        contract_address=setup["contract_address"],
+        function="get_dispute_status",
+        args=[],
+    )
+    assert result["dispute_raised"] is True
+
+
+@pytest.mark.order(4)
+def test_freelancer_submits_evidence(setup):
+    setup["client"].send_transaction(
+        sender=setup["freelancer_account"],
+        contract_address=setup["contract_address"],
+        function="raise_dispute",
+        args=["The README is in the repo root. Error handling is in scraper.py lines 45-67."],
+    )
+    result = setup["client"].call_contract(
+        sender=setup["client_account"],
+        contract_address=setup["contract_address"],
+        function="get_dispute_status",
+        args=[],
+    )
+    assert "README" in result["freelancer_evidence"]
+
+
+@pytest.mark.order(5)
+def test_resolve_dispute(setup):
+    setup["client"].send_transaction(
+        sender=setup["third_party_account"],
+        contract_address=setup["contract_address"],
+        function="resolve_dispute",
+        args=[],
+    )
+    verdict = setup["client"].call_contract(
+        sender=setup["third_party_account"],
+        contract_address=setup["contract_address"],
+        function="get_verdict",
+        args=[],
+    )
+    assert verdict in ("freelancer", "client", "draw")
+
+
+# ── Negative / access control tests ──────────────────────────────────────────
+
+@pytest.mark.order(6)
+def test_non_freelancer_cannot_submit_deliverables(setup):
+    """Client should not be able to submit deliverables."""
+    try:
+        setup["client"].send_transaction(
+            sender=setup["client_account"],
+            contract_address=setup["contract_address"],
+            function="submit_deliverables",
+            args=["https://malicious-override.com"],
+        )
+        assert False, "Expected an exception but none was raised."
+    except Exception as e:
+        assert "Only the freelancer" in str(e) or "resolved" in str(e)
+
+
+@pytest.mark.order(7)
+def test_cannot_submit_evidence_twice(setup):
+    """A party cannot overwrite their evidence once submitted."""
+    try:
+        setup["client"].send_transaction(
+            sender=setup["client_account"],
+            contract_address=setup["contract_address"],
+            function="raise_dispute",
+            args=["Trying to overwrite my evidence."],
+        )
+        assert False, "Expected an exception but none was raised."
+    except Exception as e:
+        assert "already submitted" in str(e) or "resolved" in str(e)
+
+
+@pytest.mark.order(8)
+def test_double_resolution_is_rejected(setup):
+    """Calling resolve_dispute a second time should fail."""
+    try:
+        setup["client"].send_transaction(
+            sender=setup["third_party_account"],
+            contract_address=setup["contract_address"],
+            function="resolve_dispute",
+            args=[],
+        )
+        assert False, "Expected an exception but none was raised."
+    except Exception as e:
+        assert "already been resolved" in str(e)