# v0.2.16 # { "Depends": "py-genlayer:1jb45aa8ynh2a9c9xn3b7qqh8sm5q93hwfp7jqmwsfhh8jpz09h6" } from genlayer import * import hashlib import json import typing from dataclasses import dataclass # ThresholdMilestoneEscrow - A qualitative milestone escrow with discrete payout # consensus, evidence integrity hashing, and economic appellate review. # Pure ASCII encoding enforced for Studio and GenVM compatibility. @allow_storage @dataclass class Milestone: payer: str # hex worker: str # hex criteria: str evidence_url_prefix: str escrow: bigint # GEN wei appeal_bond: bigint # GEN wei required from an appellant proposal_deadline: bigint # unix secs appeal_window_secs: bigint evidence_urls_json: str # JSON array of URLs the worker submitted verdict: str # "" | ACHIEVED | PARTIAL | NOT_ACHIEVED bucket: bigint # 0 | 50 | 100 confidence_band: bigint # 0=low, 1=med, 2=high reason: str evidence_hash: str # sha256 hex over sorted urls + fetched lengths status: str # OPEN | EVIDENCE_SUBMITTED | ADJUDICATED | APPEALED | RESOLVED | FINAL adjudicated_at: bigint appellant: str # hex or "" supplemental_url: str worker_paid: bool payer_paid: bool def _norm_verdict(raw: str) -> str: v = str(raw or "").strip().upper() if "NOT" in v or "FAIL" in v or "REJECT" in v: return "NOT_ACHIEVED" if "PARTIAL" in v or "INCOMPLETE" in v or "HALF" in v: return "PARTIAL" if "ACHIEVE" in v or "PASS" in v or "SUCCESS" in v or "COMPLETE" in v: return "ACHIEVED" return "PARTIAL" def _band(conf: typing.Any) -> int: try: c = int(conf) except Exception: c = 0 if c < 35: return 0 if c < 80: return 1 return 2 def _evidence_hash(urls_and_lengths: typing.List[typing.Tuple[str, int]]) -> str: sorted_items = sorted(urls_and_lengths, key=lambda x: x[0]) raw = "|".join(f"{u}:{length}" for u, length in sorted_items) return hashlib.sha256(raw.encode("ascii")).hexdigest() def _addr_str(a: typing.Any) -> str: try: return a.as_hex.lower() except Exception: return str(a).lower() def _is_valid_hex_address(addr: str) -> bool: if not isinstance(addr, str): return False clean = addr.strip().lower() if not clean.startswith("0x") or len(clean) != 42: return False hex_chars = "0123456789abcdef" return all(c in hex_chars for c in clean[2:]) def _now_epoch() -> bigint: try: return bigint(int(gl.vm.get_timestamp().timestamp())) except Exception: try: return bigint(int(gl.block.timestamp)) except Exception: return bigint(0) def _run_nondet(leader_fn, validator_fn): fn = ( getattr(gl.vm, "run_nondet_default", None) or getattr(gl.vm, "run_nondet", None) or gl.vm.run_nondet_unsafe ) return fn(leader_fn, validator_fn) def _coerce_verdict_and_bucket(verdict: str, bucket: int, band: int) -> typing.Tuple[str, int, int]: v_norm = _norm_verdict(verdict) b_val = 0 if bucket >= 75: b_val = 100 elif bucket >= 25: b_val = 50 else: b_val = 0 expected_bucket = 100 if v_norm == "ACHIEVED" else (50 if v_norm == "PARTIAL" else 0) if expected_bucket != b_val: safer_bucket = min(expected_bucket, b_val) safer_verdict = "ACHIEVED" if safer_bucket == 100 else ("PARTIAL" if safer_bucket == 50 else "NOT_ACHIEVED") penalized_band = max(0, band - 1) return safer_verdict, safer_bucket, penalized_band return v_norm, b_val, band class Contract(gl.Contract): milestones: TreeMap[str, Milestone] next_id: bigint total_escrowed: bigint total_paid_out: bigint def __init__(self): self.next_id = bigint(0) self.total_escrowed = bigint(0) self.total_paid_out = bigint(0) @gl.public.write.payable def open_milestone( self, worker_hex: str, criteria: str, evidence_url_prefix: str, proposal_deadline_secs: int, appeal_window_secs: int, ) -> None: if int(gl.message.value) <= 0: raise gl.vm.UserError("Escrow deposit must be positive") if not _is_valid_hex_address(worker_hex): raise gl.vm.UserError("Worker address must be a valid 42-char hex string") if not criteria or not criteria.strip(): raise gl.vm.UserError("Criteria cannot be empty") if not evidence_url_prefix.startswith("https://"): raise gl.vm.UserError("evidence_url_prefix must start with https://") if proposal_deadline_secs <= 0: raise gl.vm.UserError("proposal_deadline_secs must be positive") if appeal_window_secs <= 0: raise gl.vm.UserError("appeal_window_secs must be positive") caller = _addr_str(gl.message.sender) worker_clean = worker_hex.strip().lower() now = _now_epoch() escrow_val = bigint(gl.message.value) # Appeal bond is fixed at 10% of escrow, with a minimum floor of 0.001 GEN (10^15 wei) bond = escrow_val // bigint(10) if bond < bigint(10**15): bond = bigint(10**15) mid = str(self.next_id) self.milestones[mid] = Milestone( payer=caller, worker=worker_clean, criteria=criteria.strip(), evidence_url_prefix=evidence_url_prefix.strip(), escrow=escrow_val, appeal_bond=bond, proposal_deadline=now + bigint(proposal_deadline_secs), appeal_window_secs=bigint(appeal_window_secs), evidence_urls_json="[]", verdict="", bucket=bigint(0), confidence_band=bigint(0), reason="", evidence_hash="", status="OPEN", adjudicated_at=bigint(0), appellant="", supplemental_url="", worker_paid=False, payer_paid=False, ) self.next_id = self.next_id + bigint(1) self.total_escrowed = self.total_escrowed + escrow_val @gl.public.write def submit_evidence(self, milestone_id: str, evidence_urls_json: str) -> None: if milestone_id not in self.milestones: raise gl.vm.UserError("Milestone not found") m = self.milestones[milestone_id] if m.status != "OPEN": raise gl.vm.UserError("Milestone is not in OPEN status") caller = _addr_str(gl.message.sender) if caller != m.worker: raise gl.vm.UserError("Only assigned worker can submit evidence") now = _now_epoch() if now >= m.proposal_deadline: raise gl.vm.UserError("Proposal deadline has passed") try: urls = json.loads(evidence_urls_json) except Exception: raise gl.vm.UserError("evidence_urls_json must be valid JSON") if not isinstance(urls, list) or len(urls) < 2 or len(urls) > 4: raise gl.vm.UserError("Must provide between 2 and 4 evidence URLs") for u in urls: if not isinstance(u, str) or not u.startswith("https://"): raise gl.vm.UserError("Each evidence URL must be an https URL string") if not u.startswith(m.evidence_url_prefix): raise gl.vm.UserError("Each URL must start with the specified evidence_url_prefix") m.evidence_urls_json = json.dumps(urls) m.status = "EVIDENCE_SUBMITTED" self.milestones[milestone_id] = m @gl.public.write def adjudicate(self, milestone_id: str) -> None: if milestone_id not in self.milestones: raise gl.vm.UserError("Milestone not found") m = self.milestones[milestone_id] if m.status != "EVIDENCE_SUBMITTED": raise gl.vm.UserError("Milestone must be in EVIDENCE_SUBMITTED status") # Capture storage locals before entering nondeterministic block criteria = m.criteria urls_raw = m.evidence_urls_json urls = json.loads(urls_raw) def leader_fn(): evidence_pairs = [] fetched_texts = [] has_error = False for u in urls: try: text = gl.nondet.web.render(u, mode="text") if not text or not text.strip(): has_error = True evidence_pairs.append((u, 0)) fetched_texts.append(f"URL: {u}\nFETCH EMPTY") else: rendered = (text or "")[:4000] evidence_pairs.append((u, len(rendered))) fetched_texts.append(f"URL: {u}\nCONTENT:\n{rendered}") except Exception: has_error = True evidence_pairs.append((u, 0)) fetched_texts.append(f"URL: {u}\nFETCH ERROR") ev_hash = _evidence_hash(evidence_pairs) if has_error: # Coerce to safe non-punitive default if web fetch failed return json.dumps({ "verdict": "PARTIAL", "bucket": 0, "confidence": 0, "confidence_band": 0, "reason": "Web fetch failed or returned empty during adjudication.", "evidence_hash": ev_hash, }, sort_keys=True) prompt = f"""You are an impartial decentralized court jury adjudicating a milestone deliverable. Criteria for completion: {criteria} Evidence submitted: {"---".join(fetched_texts)} Evaluate the deliverable against the criteria. Assign a payout bucket: - 100: Criteria completely ACHIEVED. - 50: Criteria PARTIALLY achieved with minor non-critical gaps. - 0: Criteria NOT_ACHIEVED or substantial failure. Respond ONLY with a JSON object: {{"verdict": "ACHIEVED"|"PARTIAL"|"NOT_ACHIEVED", "bucket": 100|50|0, "confidence": 0-100, "reason": ""}}""" res = gl.nondet.exec_prompt(prompt, response_format="json") raw_v = res.get("verdict", "PARTIAL") raw_b = int(res.get("bucket", 0)) raw_conf = int(res.get("confidence", 0)) raw_reason = str(res.get("reason", "")).strip()[:400] band_val = _band(raw_conf) final_v, final_b, final_band = _coerce_verdict_and_bucket(raw_v, raw_b, band_val) return json.dumps({ "verdict": final_v, "bucket": final_b, "confidence": raw_conf, "confidence_band": final_band, "reason": raw_reason or "Jury adjudication complete.", "evidence_hash": ev_hash, }, sort_keys=True) def validator_fn(leader_res: typing.Any) -> bool: if not isinstance(leader_res, gl.vm.Return): return False try: leader = json.loads(leader_res.calldata) except Exception: return False mine = json.loads(leader_fn()) if _norm_verdict(leader.get("verdict")) != _norm_verdict(mine.get("verdict")): return False if int(leader.get("bucket", -1)) != int(mine.get("bucket", -2)): return False if int(leader.get("confidence_band", -1)) != int(mine.get("confidence_band", -2)): return False if str(leader.get("evidence_hash", "")) != str(mine.get("evidence_hash", "")): return False return True raw_payload = _run_nondet(leader_fn, validator_fn) payload = json.loads(raw_payload) m.verdict = payload["verdict"] m.bucket = bigint(payload["bucket"]) m.confidence_band = bigint(payload["confidence_band"]) m.reason = payload["reason"] m.evidence_hash = payload["evidence_hash"] m.status = "ADJUDICATED" m.adjudicated_at = _now_epoch() self.milestones[milestone_id] = m @gl.public.write.payable def appeal(self, supplemental_url: str, reason: str, milestone_id: str) -> None: if milestone_id not in self.milestones: raise gl.vm.UserError("Milestone not found") m = self.milestones[milestone_id] if m.status != "ADJUDICATED": raise gl.vm.UserError("Milestone is not in ADJUDICATED status") caller = _addr_str(gl.message.sender) if caller != m.payer and caller != m.worker: raise gl.vm.UserError("Only payer or worker may appeal") now = _now_epoch() if now >= m.adjudicated_at + m.appeal_window_secs: raise gl.vm.UserError("Appeal window has closed") if int(gl.message.value) < int(m.appeal_bond): raise gl.vm.UserError("Attached deposit is less than required appeal bond") if not supplemental_url.startswith("https://"): raise gl.vm.UserError("supplemental_url must start with https://") if not reason or not reason.strip(): raise gl.vm.UserError("Appeal reason cannot be empty") m.appellant = caller m.supplemental_url = supplemental_url.strip() m.status = "APPEALED" self.milestones[milestone_id] = m @gl.public.write def resolve_appeal(self, milestone_id: str) -> None: if milestone_id not in self.milestones: raise gl.vm.UserError("Milestone not found") m = self.milestones[milestone_id] if m.status != "APPEALED": raise gl.vm.UserError("Milestone must be in APPEALED status") # Capture storage locals criteria = m.criteria original_verdict = m.verdict original_bucket = int(m.bucket) original_reason = m.reason urls = json.loads(m.evidence_urls_json) supplemental_url = m.supplemental_url def leader_fn(): evidence_pairs = [] fetched_texts = [] has_error = False for u in urls: try: text = gl.nondet.web.render(u, mode="text") if not text or not text.strip(): has_error = True evidence_pairs.append((u, 0)) else: rendered = (text or "")[:3000] evidence_pairs.append((u, len(rendered))) fetched_texts.append(f"PRIMARY URL: {u}\nCONTENT:\n{rendered}") except Exception: has_error = True evidence_pairs.append((u, 0)) try: supp_text = gl.nondet.web.render(supplemental_url, mode="text") if not supp_text or not supp_text.strip(): has_error = True evidence_pairs.append((supplemental_url, 0)) else: supp_rendered = (supp_text or "")[:3000] evidence_pairs.append((supplemental_url, len(supp_rendered))) fetched_texts.append(f"SUPPLEMENTAL URL: {supplemental_url}\nCONTENT:\n{supp_rendered}") except Exception: has_error = True evidence_pairs.append((supplemental_url, 0)) if has_error: return json.dumps({ "new_verdict": original_verdict, "new_bucket": original_bucket, "confidence": 0, "confidence_band": 0, "reason": "Appellate web fetch encountered error; original verdict sustained.", "overturned": False, }, sort_keys=True) prompt = f"""You are an appellate jury on a decentralized court reviewing an appealed milestone. Criteria: {criteria} Original Verdict: {original_verdict} (Bucket: {original_bucket}) Original Rationale: {original_reason} Expanded evidence including appellant supplement: {"---".join(fetched_texts)} Re-evaluate the deliverable in light of the supplemental evidence. Choose new payout bucket (100, 50, or 0) and verdict (ACHIEVED, PARTIAL, NOT_ACHIEVED). Respond ONLY with a JSON object: {{"new_verdict": "ACHIEVED"|"PARTIAL"|"NOT_ACHIEVED", "new_bucket": 100|50|0, "confidence": 0-100, "reason": ""}}""" res = gl.nondet.exec_prompt(prompt, response_format="json") raw_v = res.get("new_verdict", original_verdict) raw_b = int(res.get("new_bucket", original_bucket)) raw_conf = int(res.get("confidence", 0)) raw_reason = str(res.get("reason", "")).strip()[:400] band_val = _band(raw_conf) final_v, final_b, final_band = _coerce_verdict_and_bucket(raw_v, raw_b, band_val) # Overturned is derived deterministically from the delta between new and original bucket overturned = (final_b != original_bucket) return json.dumps({ "new_verdict": final_v, "new_bucket": final_b, "confidence": raw_conf, "confidence_band": final_band, "reason": raw_reason or "Appellate review completed.", "overturned": overturned, }, sort_keys=True) def validator_fn(leader_res: typing.Any) -> bool: if not isinstance(leader_res, gl.vm.Return): return False try: leader = json.loads(leader_res.calldata) except Exception: return False mine = json.loads(leader_fn()) if _norm_verdict(leader.get("new_verdict")) != _norm_verdict(mine.get("new_verdict")): return False if int(leader.get("new_bucket", -1)) != int(mine.get("new_bucket", -2)): return False if int(leader.get("confidence_band", -1)) != int(mine.get("confidence_band", -2)): return False if bool(leader.get("overturned")) != bool(mine.get("overturned")): return False return True raw_payload = _run_nondet(leader_fn, validator_fn) payload = json.loads(raw_payload) m.verdict = payload["new_verdict"] m.bucket = bigint(payload["new_bucket"]) m.confidence_band = bigint(payload["confidence_band"]) m.reason = payload["reason"] m.status = "RESOLVED" self.milestones[milestone_id] = m @gl.public.write def finalize(self, milestone_id: str) -> None: if milestone_id not in self.milestones: raise gl.vm.UserError("Milestone not found") m = self.milestones[milestone_id] now = _now_epoch() can_finalize = False if m.status == "ADJUDICATED" and now >= m.adjudicated_at + m.appeal_window_secs: can_finalize = True elif m.status == "RESOLVED": can_finalize = True if not can_finalize: raise gl.vm.UserError("Milestone is not ready for finalization") m.status = "FINAL" self.milestones[milestone_id] = m @gl.public.write def withdraw(self, milestone_id: str) -> None: if milestone_id not in self.milestones: raise gl.vm.UserError("Milestone not found") m = self.milestones[milestone_id] if m.status != "FINAL": raise gl.vm.UserError("Milestone is not in FINAL status") caller = _addr_str(gl.message.sender) if caller != m.worker and caller != m.payer: raise gl.vm.UserError("Caller is not a party to this milestone") escrow_val = int(m.escrow) bucket_val = int(m.bucket) worker_escrow_share = (escrow_val * bucket_val) // 100 payer_escrow_share = escrow_val - worker_escrow_share worker_bond_bonus = 0 payer_bond_bonus = 0 # Settle appeal bond if an appeal took place if m.appellant: appeal_bond_val = int(m.appeal_bond) # Check if bucket shifted in appellant's favor: # Worker appellant favors higher bucket. # Payer appellant favors lower bucket. if m.appellant == m.worker: # If worker won (bucket > original), bond returned to worker; else forfeited to payer # In RESOLVED status, bucket is final_b if bucket_val > 0: worker_bond_bonus += appeal_bond_val else: payer_bond_bonus += appeal_bond_val elif m.appellant == m.payer: # If payer won (bucket shifted down), bond returned to payer; else forfeited to worker if bucket_val < 100: payer_bond_bonus += appeal_bond_val else: worker_bond_bonus += appeal_bond_val payout_amount = 0 if caller == m.worker: if m.worker_paid: raise gl.vm.UserError("Worker has already withdrawn payout") payout_amount = worker_escrow_share + worker_bond_bonus m.worker_paid = True elif caller == m.payer: if m.payer_paid: raise gl.vm.UserError("Payer has already withdrawn payout") payout_amount = payer_escrow_share + payer_bond_bonus m.payer_paid = True self.milestones[milestone_id] = m self.total_paid_out = self.total_paid_out + bigint(payout_amount) if payout_amount > 0: gl.get_contract_at(gl.message.sender).emit_transfer(value=u256(payout_amount)) @gl.public.view def get_milestone(self, milestone_id: str) -> str: if milestone_id not in self.milestones: raise gl.vm.UserError("Milestone not found") m = self.milestones[milestone_id] return json.dumps({ "id": milestone_id, "payer": m.payer, "worker": m.worker, "criteria": m.criteria, "evidence_url_prefix": m.evidence_url_prefix, "escrow": int(m.escrow), "appeal_bond": int(m.appeal_bond), "proposal_deadline": int(m.proposal_deadline), "appeal_window_secs": int(m.appeal_window_secs), "evidence_urls": json.loads(m.evidence_urls_json), "verdict": m.verdict, "bucket": int(m.bucket), "confidence_band": int(m.confidence_band), "reason": m.reason, "evidence_hash": m.evidence_hash, "status": m.status, "adjudicated_at": int(m.adjudicated_at), "appellant": m.appellant, "supplemental_url": m.supplemental_url, "worker_paid": m.worker_paid, "payer_paid": m.payer_paid, }) @gl.public.view def get_totals(self) -> str: return json.dumps({ "next_id": int(self.next_id), "total_escrowed": int(self.total_escrowed), "total_paid_out": int(self.total_paid_out), })