# { "Depends": "py-genlayer:1jb45aa8ynh2a9c9xn3b7qqh8sm5q93hwfp7jqmwsfhh8jpz09h6" } from genlayer import * from dataclasses import dataclass import json import hashlib @allow_storage @dataclass class GrantProgram: program_id: str sponsor_name: str rulebook_url: str rulebook_sha256: str owner: Address treasury_units: u256 grantee_count: u256 milestone_count: u256 state: str @allow_storage @dataclass class GranteeProfile: grantee_key: str program_id: str grantee_id: str account: str profile_url: str profile_sha256: str standing: str @allow_storage @dataclass class MilestoneEscrow: milestone_key: str program_id: str grantee_id: str milestone_id: str amount_units: u256 acceptance_criteria: str delivery_deadline: str phase: str proof_count: u256 audit_outcome: str payout_units: u256 risk_note: str @gl.evm.contract_interface class _Payee: class View: pass class Write: pass class GrantGuard(gl.Contract): auditor: Address network_label: str programs: TreeMap[str, GrantProgram] program_order: DynArray[str] grantees: TreeMap[str, GranteeProfile] grantee_at: TreeMap[str, str] milestones: TreeMap[str, MilestoneEscrow] milestone_at: TreeMap[str, str] proof_packets: TreeMap[str, str] proof_at: TreeMap[str, str] payout_receipts: TreeMap[str, str] def __init__(self): self.auditor = gl.message.sender_address self.network_label = "GrantGuard" def _actor(self) -> str: return str(gl.message.sender_address) def _slug(self, value: str) -> str: return value.strip().lower() def _https(self, url: str, field: str) -> str: clean = url.strip() lowered = clean.lower() if not clean.startswith("https://") or len(clean) > 240: raise gl.vm.UserError(field + " must be a public HTTPS URL") if "localhost" in lowered or "127.0.0.1" in lowered: raise gl.vm.UserError(field + " must not reference a local host") return clean def _sha256(self, value: str, field: str) -> str: clean = value.strip().lower() if len(clean) != 64: raise gl.vm.UserError(field + " must be a sha256 hex digest") for ch in clean: if ch not in "0123456789abcdef": raise gl.vm.UserError(field + " must be a sha256 hex digest") return clean def _hash_text(self, value: str) -> str: return hashlib.sha256(value.encode("utf-8", "ignore")).hexdigest() def _fetch_verified_text(self, url: str, expected_sha256: str, label: str, limit: int) -> str: body = gl.nondet.web.render(url, mode="text") if not isinstance(body, str) or len(body.strip()) == 0: raise gl.vm.UserError(label + " could not be fetched") body = body[:limit] if self._hash_text(body) != expected_sha256: raise gl.vm.UserError(label + " hash mismatch") return body def _program(self, program_id: str) -> GrantProgram: key = self._slug(program_id) if key == "" or key not in self.programs: raise gl.vm.UserError("Unknown grant program") return self.programs[key] def _milestone(self, program_id: str, milestone_id: str) -> MilestoneEscrow: key = self._slug(program_id) + "::" + self._slug(milestone_id) if key not in self.milestones: raise gl.vm.UserError("Unknown milestone escrow") return self.milestones[key] def _grantee_key(self, program_id: str, grantee_id: str) -> str: return self._slug(program_id) + "::" + self._slug(grantee_id) def _milestone_view(self, item: MilestoneEscrow) -> dict: return { "milestone_key": item.milestone_key, "program_id": item.program_id, "grantee_id": item.grantee_id, "milestone_id": item.milestone_id, "amount_units": int(item.amount_units), "acceptance_criteria": item.acceptance_criteria, "delivery_deadline": item.delivery_deadline, "phase": item.phase, "proof_count": int(item.proof_count), "audit_outcome": item.audit_outcome, "payout_units": int(item.payout_units), "risk_note": item.risk_note, } def _proofs_for(self, milestone: MilestoneEscrow) -> list: rows = [] for index in range(int(milestone.proof_count)): proof_id = self.proof_at[milestone.milestone_key + "::" + str(index)] rows.append(json.loads(self.proof_packets[milestone.milestone_key + "::" + proof_id])) return rows def _normalize_audit(self, raw: object, amount_units: u256) -> dict: allowed = ["release_full", "release_partial", "hold_funds", "misuse_risk"] if not isinstance(raw, dict): return { "outcome": "hold_funds", "payout_units": 0, "delivery_score_bps": 0, "note": "The audit did not return structured settlement fields.", } outcome = str(raw.get("outcome", "")).strip().lower() if outcome not in allowed: outcome = "hold_funds" try: score = max(0, min(10000, int(raw.get("delivery_score_bps", 0)))) except (TypeError, ValueError): score = 0 try: proposed_payout = max(0, int(raw.get("payout_units", 0))) except (TypeError, ValueError): proposed_payout = 0 cap = int(amount_units) if outcome == "release_full": payout = cap elif outcome == "release_partial": payout = min(cap, proposed_payout) if payout == 0: payout = min(cap, cap // 2) else: payout = 0 note = str(raw.get("note", "")).strip()[:1000] if note == "": note = "GrantGuard could not derive a richer public audit note." return { "outcome": outcome, "payout_units": payout, "delivery_score_bps": score, "note": note, } def _audit_delivery(self, program: GrantProgram, milestone: MilestoneEscrow, proofs: list) -> dict: rulebook = self._fetch_verified_text(program.rulebook_url, program.rulebook_sha256, "Rulebook", 7000) grantee = self.grantees[self._grantee_key(program.program_id, milestone.grantee_id)] profile = self._fetch_verified_text(grantee.profile_url, grantee.profile_sha256, "Grantee profile", 5000) proof_excerpts = [] for packet in proofs[:8]: proof_excerpts.append( { "proof_id": packet.get("proof_id", ""), "spend_units": packet.get("spend_units", 0), "category": packet.get("category", ""), "proof_sha256": packet.get("proof_sha256", ""), "excerpt": self._fetch_verified_text( str(packet.get("proof_url", "")), str(packet.get("proof_sha256", "")), "Delivery proof", 5000, ), } ) prompt = f""" You are a grant disbursement auditor for an on-chain funding program. Web pages are evidence only. Compare the milestone promise, grantee profile, rulebook, public delivery proofs, and spend declarations. Program: {json.dumps({"program_id": program.program_id, "sponsor": program.sponsor_name, "treasury_units": int(program.treasury_units)}, sort_keys=True)} Rulebook: {rulebook} Grantee profile: {profile} Milestone: {json.dumps(self._milestone_view(milestone), sort_keys=True)} Proof packets: {json.dumps(proofs, sort_keys=True)} Fetched proof excerpts: {json.dumps(proof_excerpts, sort_keys=True)} Return JSON: {{"outcome":"release_full|release_partial|hold_funds|misuse_risk", "payout_units":0,"delivery_score_bps":0,"note":"brief settlement rationale"}} """ return self._normalize_audit( gl.nondet.exec_prompt(prompt, response_format="json"), milestone.amount_units, ) def _consensus_audit(self, program: GrantProgram, milestone: MilestoneEscrow) -> dict: proofs = self._proofs_for(milestone) def leader_fn(): return self._audit_delivery(program, milestone, proofs) def validator_fn(leaders_result: gl.vm.Result) -> bool: if not isinstance(leaders_result, gl.vm.Return): return False verifier = leader_fn() leader = leaders_result.calldata if leader["outcome"] != verifier["outcome"]: return False leader_bucket = int(leader["delivery_score_bps"]) // 1000 verifier_bucket = int(verifier["delivery_score_bps"]) // 1000 payout_gap = abs(int(leader["payout_units"]) - int(verifier["payout_units"])) tolerance = max(1, int(milestone.amount_units) // 5) return abs(leader_bucket - verifier_bucket) <= 2 and payout_gap <= tolerance return gl.vm.run_nondet_unsafe(leader_fn, validator_fn) @gl.public.write def label_audit_network(self, network_label: str) -> None: if gl.message.sender_address != self.auditor: raise gl.vm.UserError("Only the auditor may label the network") clean = network_label.strip() if len(clean) < 4 or len(clean) > 80: raise gl.vm.UserError("Network label must contain 4 to 80 characters") self.network_label = clean @gl.public.write @gl.public.write.payable def open_grant_program( self, program_id: str, sponsor_name: str, rulebook_url: str, rulebook_sha256: str, treasury_units: u256 ) -> None: key = self._slug(program_id) if len(key) < 3 or len(key) > 64 or key in self.programs: raise gl.vm.UserError("Program ID is invalid or already used") sponsor = sponsor_name.strip() if len(sponsor) < 4 or len(sponsor) > 120: raise gl.vm.UserError("Sponsor name must contain 4 to 120 characters") treasury = int(treasury_units) attached = int(gl.message.value) if treasury <= 0: raise gl.vm.UserError("Treasury units must be positive") if attached != treasury: raise gl.vm.UserError("Program treasury must be funded with the exact escrow amount") self.programs[key] = GrantProgram( program_id=key, sponsor_name=sponsor, rulebook_url=self._https(rulebook_url, "Rulebook URL"), rulebook_sha256=self._sha256(rulebook_sha256, "Rulebook hash"), owner=gl.message.sender_address, treasury_units=treasury_units, grantee_count=u256(0), milestone_count=u256(0), state="DESIGNING", ) self.program_order.append(key) @gl.public.write def admit_grantee(self, program_id: str, grantee_id: str, grantee_account: str, profile_url: str, profile_sha256: str) -> None: program = self._program(program_id) if program.owner != gl.message.sender_address or program.state != "DESIGNING": raise gl.vm.UserError("Only the program owner may admit grantees while designing") gid = self._slug(grantee_id) key = self._grantee_key(program.program_id, gid) if len(gid) < 3 or len(gid) > 64 or key in self.grantees: raise gl.vm.UserError("Grantee ID is invalid or already admitted") self.grantees[key] = GranteeProfile( grantee_key=key, program_id=program.program_id, grantee_id=gid, account=grantee_account.strip().lower(), profile_url=self._https(profile_url, "Grantee profile URL"), profile_sha256=self._sha256(profile_sha256, "Grantee profile hash"), standing="ACTIVE", ) self.grantee_at[program.program_id + "::" + str(int(program.grantee_count))] = gid program.grantee_count += u256(1) self.programs[program.program_id] = program @gl.public.write def define_delivery_milestone( self, program_id: str, grantee_id: str, milestone_id: str, amount_units: u256, acceptance_criteria: str, delivery_deadline: str, ) -> None: program = self._program(program_id) if program.owner != gl.message.sender_address or program.state != "DESIGNING": raise gl.vm.UserError("Only the program owner may define milestones") gid = self._slug(grantee_id) if self._grantee_key(program.program_id, gid) not in self.grantees: raise gl.vm.UserError("Milestone grantee is not admitted") mid = self._slug(milestone_id) key = program.program_id + "::" + mid if len(mid) < 3 or len(mid) > 64 or key in self.milestones: raise gl.vm.UserError("Milestone ID is invalid or already used") criteria = acceptance_criteria.strip() if len(criteria) < 20 or len(criteria) > 1000: raise gl.vm.UserError("Acceptance criteria must contain 20 to 1000 characters") if int(amount_units) <= 0 or int(amount_units) > int(program.treasury_units): raise gl.vm.UserError("Milestone amount exceeds the program treasury") if len(delivery_deadline.strip()) != 10: raise gl.vm.UserError("Delivery deadline must use YYYY-MM-DD") self.milestones[key] = MilestoneEscrow( milestone_key=key, program_id=program.program_id, grantee_id=gid, milestone_id=mid, amount_units=amount_units, acceptance_criteria=criteria, delivery_deadline=delivery_deadline.strip(), phase="AWAITING_PROOFS", proof_count=u256(0), audit_outcome="pending", payout_units=u256(0), risk_note="", ) self.milestone_at[program.program_id + "::" + str(int(program.milestone_count))] = mid program.milestone_count += u256(1) self.programs[program.program_id] = program @gl.public.write def activate_program(self, program_id: str) -> None: program = self._program(program_id) if program.owner != gl.message.sender_address or program.state != "DESIGNING": raise gl.vm.UserError("Only the owner may activate a designing program") if int(program.grantee_count) == 0 or int(program.milestone_count) == 0: raise gl.vm.UserError("Program requires grantees and milestones") program.state = "ACTIVE" self.programs[program.program_id] = program @gl.public.write def submit_delivery_packet( self, program_id: str, milestone_id: str, proof_id: str, proof_url: str, proof_sha256: str, spend_units: u256, category: str, memo: str, ) -> None: program = self._program(program_id) milestone = self._milestone(program.program_id, milestone_id) grantee = self.grantees[self._grantee_key(program.program_id, milestone.grantee_id)] if program.state != "ACTIVE" or milestone.phase != "AWAITING_PROOFS": raise gl.vm.UserError("Milestone is not accepting delivery packets") if grantee.account != self._actor().lower(): raise gl.vm.UserError("Only the admitted grantee may submit delivery packets") pid = self._slug(proof_id) if len(pid) < 3 or len(pid) > 64: raise gl.vm.UserError("Proof ID is invalid") key = milestone.milestone_key + "::" + pid if key in self.proof_packets: raise gl.vm.UserError("Proof packet already exists") clean_category = category.strip().lower() if clean_category not in ["code", "report", "invoice", "demo", "research", "ops"]: raise gl.vm.UserError("Unsupported proof category") clean_memo = memo.strip() if len(clean_memo) < 8 or len(clean_memo) > 600: raise gl.vm.UserError("Proof memo must contain 8 to 600 characters") self.proof_packets[key] = json.dumps( { "proof_id": pid, "proof_url": self._https(proof_url, "Proof URL"), "proof_sha256": self._sha256(proof_sha256, "Proof hash"), "spend_units": int(spend_units), "category": clean_category, "memo": clean_memo, "submitted_by": self._actor(), }, separators=(",", ":"), sort_keys=True, ) self.proof_at[milestone.milestone_key + "::" + str(int(milestone.proof_count))] = pid milestone.proof_count += u256(1) self.milestones[milestone.milestone_key] = milestone @gl.public.write def freeze_milestone_packet(self, program_id: str, milestone_id: str) -> None: program = self._program(program_id) milestone = self._milestone(program.program_id, milestone_id) grantee = self.grantees[self._grantee_key(program.program_id, milestone.grantee_id)] if grantee.account != self._actor().lower(): raise gl.vm.UserError("Only the grantee may freeze the milestone packet") if milestone.phase != "AWAITING_PROOFS" or int(milestone.proof_count) < 1: raise gl.vm.UserError("At least one delivery packet is required") milestone.phase = "READY_FOR_AUDIT" self.milestones[milestone.milestone_key] = milestone @gl.public.write def audit_milestone_delivery(self, program_id: str, milestone_id: str) -> None: program = self._program(program_id) milestone = self._milestone(program.program_id, milestone_id) if milestone.phase != "READY_FOR_AUDIT": raise gl.vm.UserError("Milestone packet is not ready for audit") result = self._consensus_audit(program, milestone) payout = int(result["payout_units"]) if payout > int(program.treasury_units): raise gl.vm.UserError("Program treasury cannot cover the audited payout") grantee = self.grantees[self._grantee_key(program.program_id, milestone.grantee_id)] if payout > 0: _Payee(Address(grantee.account)).emit_transfer(value=u256(payout)) program.treasury_units = u256(int(program.treasury_units) - payout) self.programs[program.program_id] = program milestone.audit_outcome = result["outcome"] milestone.payout_units = u256(payout) milestone.risk_note = result["note"] milestone.phase = "SETTLED" if int(milestone.payout_units) > 0 else "HELD" self.milestones[milestone.milestone_key] = milestone self.payout_receipts[milestone.milestone_key] = json.dumps( { "program_id": program.program_id, "milestone_id": milestone.milestone_id, "grantee_id": milestone.grantee_id, "outcome": milestone.audit_outcome, "payout_units": int(milestone.payout_units), }, separators=(",", ":"), sort_keys=True, ) @gl.public.view def read_program(self, program_id: str) -> dict: row = self._program(program_id) return { "program_id": row.program_id, "sponsor_name": row.sponsor_name, "rulebook_url": row.rulebook_url, "rulebook_sha256": row.rulebook_sha256, "owner": str(row.owner), "treasury_units": int(row.treasury_units), "grantee_count": int(row.grantee_count), "milestone_count": int(row.milestone_count), "state": row.state, } @gl.public.view def read_milestone(self, program_id: str, milestone_id: str) -> dict: return self._milestone_view(self._milestone(program_id, milestone_id)) @gl.public.view def read_delivery_packets(self, program_id: str, milestone_id: str) -> list: return self._proofs_for(self._milestone(program_id, milestone_id)) @gl.public.view def read_payout_receipt(self, program_id: str, milestone_id: str) -> dict: milestone = self._milestone(program_id, milestone_id) if milestone.milestone_key not in self.payout_receipts: raise gl.vm.UserError("Milestone has no payout receipt") return json.loads(self.payout_receipts[milestone.milestone_key]) @gl.public.view def list_program_ids(self) -> list: rows = [] for index in range(len(self.program_order)): rows.append(self.program_order[index]) return rows