# { "Depends": "py-genlayer:1jb45aa8ynh2a9c9xn3b7qqh8sm5q93hwfp7jqmwsfhh8jpz09h6" } """ ProofOfShip — Autonomous Milestone & Code Delivery Verification Engine for GenLayer. The Real-World Problem ----------------------- Millions of dollars in Web3 grants, DAO bounties, and milestone-based freelance contracts are locked in escrow across the internet. Today, milestone verification is a severe operational bottleneck: 1. Manual review is slow, subjective, expensive, and non-transparent. 2. Grant managers must manually check if GitHub commits exist, if CI tests pass, if live deployment URLs are active, and whether the code changes actually fulfill the technical specifications in the grant proposal. 3. Dishonest actors game milestones with empty commits, copied templates, deleted tests, or fake staging sites, counting on fatigued human reviewers. Why GenLayer Consensus Solves This ----------------------------------- `ProofOfShip` is a decentralized, trustless milestone verification primitive. It establishes an autonomous multi-stage adjudication pipeline: - Phase 1 (Deterministic Git & Web Infrastructure Probing): Validators independently fetch GitHub commit/PR data and probe live deployment endpoints. Commit SHA existence, parent lineage, author metadata, CI/CD check runs ("success"), and HTTP 200 status codes are validated strictly. - Phase 2 (Substantive Deliverable & Anti-Gaming Analysis): Non-deterministic analysis cross-examines the actual code diff and commit messages against the milestone's written acceptance criteria. The LLM evaluates feature fulfillment (0-100 score), detects anti-gaming indicators (e.g. dummy commits, deleted test suites, superficial edits), and provides actionable remediation feedback. - Phase 3 (Comparative Equivalence & Multi-Validator Consensus): Validators rerun the pipeline independently. Deterministic facts (commit integrity, CI status, live URL health, anti-gaming flags) require strict agreement. Qualitative deliverable scores tolerate bounded confidence variance (within +/- 8 points), and both leader and validator must agree on the final milestone outcome (APPROVED, REMEDIATION_REQUIRED, or REJECTED). - Phase 4 (Deterministic Escrow Settlement): Upon consensus approval, milestone tranches are atomically released to the grantee. Deficient deliveries trigger a remediation cycle with stored guidance. """ from genlayer import * import json import typing from dataclasses import dataclass # -------------------------------------------------------------------------------------- # Error Classification Constants # -------------------------------------------------------------------------------------- ERROR_EXPECTED = "[EXPECTED]" # Deterministic business logic / access violation ERROR_EXTERNAL = "[EXTERNAL]" # Remote GitHub API or deployment endpoint 4xx error ERROR_TRANSIENT = "[TRANSIENT]" # Network timeout / 5xx error ERROR_LLM = "[LLM_ERROR]" # Model parsing / format failure (forces rotation) # -------------------------------------------------------------------------------------- # Milestone & Grant Status Constants # -------------------------------------------------------------------------------------- STATUS_CREATED = "CREATED" STATUS_ACTIVE = "ACTIVE" STATUS_COMPLETED = "COMPLETED" STATUS_CANCELLED = "CANCELLED" MILESTONE_PENDING = "PENDING" MILESTONE_IN_REVIEW = "IN_REVIEW" MILESTONE_APPROVED = "APPROVED" MILESTONE_REMEDIATION = "REMEDIATION_REQUIRED" MILESTONE_REJECTED = "REJECTED" # Thresholds APPROVAL_SCORE_THRESHOLD = 75 # Minimum score required for automatic approval REMEDIATION_SCORE_THRESHOLD = 45 # Scores between 45 and 74 require remediation MAX_EVALUATION_ATTEMPTS = 3 # Maximum review attempts per milestone MAX_SCORE_DRIFT_TOLERANCE = 8 # Allowable score variance between validator & leader # -------------------------------------------------------------------------------------- # Storage Models # -------------------------------------------------------------------------------------- @allow_storage @dataclass class Milestone: """One deliverable milestone within a grant.""" milestone_index: u32 title: str description: str deliverable_specs: str # Natural-language technical specification payout_amount_wei: u256 # Escrow payout allocated for this milestone required_ci_passing: bool # Whether GitHub CI check must be "success" required_live_deployment: bool # Whether live endpoint must return HTTP 200 status: str # MILESTONE_* attempt_count: u8 approved_at: str # ISO datetime or timestamp string @allow_storage @dataclass class DeliverySubmission: """A developer's delivery submission for a milestone.""" grant_id: str milestone_index: u32 commit_sha: str pull_request_url: str deployment_url: str submission_notes: str submitted_at: str @allow_storage @dataclass class MilestoneEvaluation: """Consensus audit record for a submitted milestone.""" evaluation_id: str # f"{grant_id}:{milestone_index}:{attempt}" grant_id: str milestone_index: u32 verdict: str # APPROVED, REMEDIATION_REQUIRED, REJECTED deliverable_score: u8 # 0 to 100 git_verified: bool # Commit existence & author confirmed ci_verified: bool # CI/CD checks confirmed deployment_verified: bool # Live deployment URL health confirmed anti_gaming_passed: bool # True if no dummy/fake commit patterns detected code_grounding_summary: str # Summary of evidence found in commit diff remediation_instructions: str # Actionable guidance if remediation is needed evaluated_at: str @allow_storage @dataclass class Grant: """A multi-milestone grant escrow agreement.""" grant_id: str title: str grantor: Address grantee: Address repo_owner: str repo_name: str total_budget_wei: u256 funded_amount_wei: u256 paid_amount_wei: u256 status: str # STATUS_* created_at: str milestones: DynArray[Milestone] # -------------------------------------------------------------------------------------- # Pure Helpers — Deterministic & Auditable on All Nodes # -------------------------------------------------------------------------------------- def _normalize_str(text: str) -> str: return " ".join(text.split()).casefold() def _parse_github_commit_response(raw_body: str) -> dict: try: data = json.loads(raw_body) except Exception: return {"valid": False, "message": "", "files_changed": 0, "changed_filenames": []} if not isinstance(data, dict) or "sha" not in data: return {"valid": False, "message": "", "files_changed": 0, "changed_filenames": []} commit_data = data.get("commit", {}) message = commit_data.get("message", "") if isinstance(commit_data, dict) else "" files = data.get("files", []) files_changed = len(files) if isinstance(files, list) else 0 changed_filenames = [] if isinstance(files, list): for f in files[:20]: if isinstance(f, dict) and "filename" in f: changed_filenames.append(f["filename"]) return { "valid": True, "sha": str(data.get("sha", "")), "message": message[:1000], "files_changed": files_changed, "changed_filenames": changed_filenames, } def _build_evaluation_prompt( milestone_title: str, milestone_specs: str, submission_notes: str, commit_sha: str, commit_message: str, changed_filenames: list[str], live_status_code: int, live_response_snippet: str, ) -> str: files_list = "\n".join([f"- {fname}" for fname in changed_filenames]) if changed_filenames else "- (No files changed listed)" return f"""You are an autonomous technical auditor evaluating a Web3 grant milestone delivery. MILESTONE REQUIREMENTS: Title: {milestone_title} Deliverable Specifications: {milestone_specs} SUBMISSION EVIDENCE (UNTRUSTED DEVELOPER DATA): Commit SHA: {commit_sha} Commit Message: {commit_message} Developer Notes: {submission_notes} Files Changed in Commit: {files_list} Live Deployment HTTP Status: {live_status_code} Live Deployment Response Excerpt: {live_response_snippet[:400]} EVALUATION INSTRUCTIONS: 1. Deliverable Fulfillment Score (0-100): - 90-100: All required specifications, code, and endpoints are fully implemented and verified. - 75-89: Material requirements met with minor non-blocking omissions. - 45-74: Partially completed; key features are missing or incomplete. - 0-44: Superficial, trivial, or wholly missing implementation. 2. Anti-Gaming Check: - Identify if the submission is a fake/dummy delivery (e.g. empty commit, only cosmetic README edits when code was required, deleted tests to fake pass, or irrelevant template copies). - Set "anti_gaming_passed": true if genuine work was done, false if scam/dummy submission. 3. Grounding Summary: - Provide a concise 2-sentence summary detailing which specific files/features demonstrate deliverable completion. 4. Remediation Guidance: - If score < 75, provide clear, bulleted steps the developer must complete to pass. Otherwise set to "None". Return JSON ONLY with this exact schema: {{ "deliverable_score": , "anti_gaming_passed": , "code_grounding_summary": "

", "remediation_instructions": "" }} """ def _parse_llm_evaluation(raw_response: typing.Any) -> dict: if isinstance(raw_response, str): try: cleaned = raw_response.strip() if cleaned.startswith("```json"): cleaned = cleaned[7:] if cleaned.startswith("```"): cleaned = cleaned[3:] if cleaned.endswith("```"): cleaned = cleaned[:-3] raw_response = json.loads(cleaned.strip()) except Exception: raise gl.vm.UserError(f"{ERROR_LLM} Invalid JSON payload from model") if not isinstance(raw_response, dict): raise gl.vm.UserError(f"{ERROR_LLM} Model response is not a JSON object") raw_score = raw_response.get("deliverable_score") if raw_score is None: for alt in ("score", "fulfillment_score", "rating"): if alt in raw_response: raw_score = raw_response[alt] break try: score = int(round(float(str(raw_score).strip()))) score = max(0, min(100, score)) except (ValueError, TypeError): raise gl.vm.UserError(f"{ERROR_LLM} Invalid or non-numeric deliverable_score: {raw_score}") raw_anti_gaming = raw_response.get("anti_gaming_passed", True) anti_gaming_passed = bool(raw_anti_gaming) grounding = str(raw_response.get("code_grounding_summary", "")).strip() remediation = str(raw_response.get("remediation_instructions", "None")).strip() return { "deliverable_score": score, "anti_gaming_passed": anti_gaming_passed, "code_grounding_summary": grounding[:500], "remediation_instructions": remediation[:500], } def _compute_verdict(score: int, anti_gaming_passed: bool, git_ok: bool, ci_ok: bool, deploy_ok: bool) -> str: if not git_ok or not ci_ok or not deploy_ok or not anti_gaming_passed: return MILESTONE_REJECTED if score >= APPROVAL_SCORE_THRESHOLD: return MILESTONE_APPROVED elif score >= REMEDIATION_SCORE_THRESHOLD: return MILESTONE_REMEDIATION else: return MILESTONE_REJECTED def _handle_leader_error(leader_result: typing.Any, leader_fn: typing.Any) -> bool: leader_msg = getattr(leader_result, "message", "") or "" try: leader_fn() return False except gl.vm.UserError as exc: validator_msg = getattr(exc, "message", "") or str(exc) if validator_msg.startswith(ERROR_EXPECTED) or validator_msg.startswith(ERROR_EXTERNAL): return validator_msg == leader_msg if validator_msg.startswith(ERROR_TRANSIENT) and leader_msg.startswith(ERROR_TRANSIENT): return True return False except Exception: return False # -------------------------------------------------------------------------------------- # Main Contract Primitive # -------------------------------------------------------------------------------------- class ProofOfShip(gl.Contract): """ Autonomous Milestone & Code Delivery Verification Engine. Coordinates multi-milestone grants, Git/CI verification, AI deliverable auditing, and trustless escrow settlement. """ grants: TreeMap[str, Grant] submissions: TreeMap[str, DeliverySubmission] evaluations: TreeMap[str, MilestoneEvaluation] grant_ids: DynArray[str] grant_counter: u64 total_escrow_deposited_wei: u256 total_escrow_paid_wei: u256 def __init__(self): self.grant_counter = u64(0) self.total_escrow_deposited_wei = u256(0) self.total_escrow_paid_wei = u256(0) # ---------------------------------------------------------------------------------- # Grant Lifecycle Management # ---------------------------------------------------------------------------------- @gl.public.write def create_grant( self, grant_id: str, title: str, grantee: Address, repo_owner: str, repo_name: str, ): """Register a new grant agreement. The caller becomes the grantor.""" if grant_id == "": raise gl.vm.UserError(f"{ERROR_EXPECTED} grant_id must not be empty") if grant_id in self.grants: raise gl.vm.UserError(f"{ERROR_EXPECTED} grant already exists: {grant_id}") if repo_owner == "" or repo_name == "": raise gl.vm.UserError(f"{ERROR_EXPECTED} repository owner and name required") self.grants[grant_id] = Grant( grant_id=grant_id, title=title, grantor=gl.message.sender_address, grantee=grantee, repo_owner=repo_owner, repo_name=repo_name, total_budget_wei=u256(0), funded_amount_wei=u256(0), paid_amount_wei=u256(0), status=STATUS_CREATED, created_at=gl.message_raw.get("datetime", ""), milestones=[], ) self.grant_ids.append(grant_id) @gl.public.write def add_milestone( self, grant_id: str, title: str, description: str, deliverable_specs: str, payout_amount_wei: u256, required_ci_passing: bool, required_live_deployment: bool, ) -> u32: """Append a deliverable milestone to an unactivated grant.""" grant = self._require_grant(grant_id) if grant.grantor != gl.message.sender_address: raise gl.vm.UserError(f"{ERROR_EXPECTED} Only grantor can add milestones") if grant.status != STATUS_CREATED: raise gl.vm.UserError(f"{ERROR_EXPECTED} Cannot add milestones to active/completed grant") if payout_amount_wei <= 0: raise gl.vm.UserError(f"{ERROR_EXPECTED} Milestone payout must be greater than zero") if deliverable_specs == "": raise gl.vm.UserError(f"{ERROR_EXPECTED} Deliverable specifications required") milestone_idx = u32(len(grant.milestones)) new_milestone = Milestone( milestone_index=milestone_idx, title=title, description=description, deliverable_specs=deliverable_specs, payout_amount_wei=payout_amount_wei, required_ci_passing=required_ci_passing, required_live_deployment=required_live_deployment, status=MILESTONE_PENDING, attempt_count=u8(0), approved_at="", ) grant.milestones.append(new_milestone) grant.total_budget_wei = u256(grant.total_budget_wei + payout_amount_wei) return milestone_idx @gl.public.write def fund_grant(self, grant_id: str, deposit_amount_wei: u256): """Fund the grant escrow. Activates the grant once fully funded.""" grant = self._require_grant(grant_id) if deposit_amount_wei <= 0: raise gl.vm.UserError(f"{ERROR_EXPECTED} Deposit must be greater than zero") grant.funded_amount_wei = u256(grant.funded_amount_wei + deposit_amount_wei) self.total_escrow_deposited_wei = u256(self.total_escrow_deposited_wei + deposit_amount_wei) if grant.funded_amount_wei >= grant.total_budget_wei and len(grant.milestones) > 0: grant.status = STATUS_ACTIVE # ---------------------------------------------------------------------------------- # Developer Delivery Submission # ---------------------------------------------------------------------------------- @gl.public.write def submit_delivery( self, grant_id: str, milestone_index: u32, commit_sha: str, pull_request_url: str, deployment_url: str, submission_notes: str, ): """Grantee submits code delivery for a specific milestone.""" grant = self._require_grant(grant_id) if grant.grantee != gl.message.sender_address: raise gl.vm.UserError(f"{ERROR_EXPECTED} Only grantee may submit delivery") if grant.status != STATUS_ACTIVE: raise gl.vm.UserError(f"{ERROR_EXPECTED} Grant is not active") if milestone_index >= len(grant.milestones): raise gl.vm.UserError(f"{ERROR_EXPECTED} Invalid milestone index: {milestone_index}") milestone = grant.milestones[milestone_index] if milestone.status == MILESTONE_APPROVED: raise gl.vm.UserError(f"{ERROR_EXPECTED} Milestone already approved") if commit_sha == "": raise gl.vm.UserError(f"{ERROR_EXPECTED} commit_sha must not be empty") if milestone.required_live_deployment and deployment_url == "": raise gl.vm.UserError(f"{ERROR_EXPECTED} Live deployment URL required for this milestone") key = f"{grant_id}:{milestone_index}" self.submissions[key] = DeliverySubmission( grant_id=grant_id, milestone_index=milestone_index, commit_sha=commit_sha, pull_request_url=pull_request_url, deployment_url=deployment_url, submission_notes=submission_notes, submitted_at=gl.message_raw.get("datetime", ""), ) milestone.status = MILESTONE_IN_REVIEW # ---------------------------------------------------------------------------------- # Consensus Adjudication & Verification # ---------------------------------------------------------------------------------- @gl.public.write def evaluate_milestone_delivery(self, grant_id: str, milestone_index: u32) -> str: """Execute multi-validator consensus evaluation of a submitted milestone.""" grant = self._require_grant(grant_id) if milestone_index >= len(grant.milestones): raise gl.vm.UserError(f"{ERROR_EXPECTED} Invalid milestone index: {milestone_index}") milestone = grant.milestones[milestone_index] if milestone.status != MILESTONE_IN_REVIEW: raise gl.vm.UserError(f"{ERROR_EXPECTED} Milestone is not submitted for review") if milestone.attempt_count >= MAX_EVALUATION_ATTEMPTS: raise gl.vm.UserError(f"{ERROR_EXPECTED} Maximum review attempts reached") sub_key = f"{grant_id}:{milestone_index}" if sub_key not in self.submissions: raise gl.vm.UserError(f"{ERROR_EXPECTED} No submission found for milestone {milestone_index}") submission = self.submissions[sub_key] # Lift storage values into plain memory variables for nondet closures repo_owner = str(grant.repo_owner) repo_name = str(grant.repo_name) commit_sha = str(submission.commit_sha) deployment_url = str(submission.deployment_url) submission_notes = str(submission.submission_notes) milestone_title = str(milestone.title) milestone_specs = str(milestone.deliverable_specs) req_ci = bool(milestone.required_ci_passing) req_deploy = bool(milestone.required_live_deployment) current_attempt = int(milestone.attempt_count) + 1 eval_result = self._run_consensus_evaluation( repo_owner=repo_owner, repo_name=repo_name, commit_sha=commit_sha, deployment_url=deployment_url, submission_notes=submission_notes, milestone_title=milestone_title, milestone_specs=milestone_specs, req_ci=req_ci, req_deploy=req_deploy, ) verdict = str(eval_result["verdict"]) deliverable_score = int(eval_result["deliverable_score"]) git_verified = bool(eval_result["git_verified"]) ci_verified = bool(eval_result["ci_verified"]) deployment_verified = bool(eval_result["deployment_verified"]) anti_gaming_passed = bool(eval_result["anti_gaming_passed"]) grounding_summary = str(eval_result["code_grounding_summary"]) remediation_instructions = str(eval_result["remediation_instructions"]) # Persist evaluation record eval_id = f"{grant_id}:{milestone_index}:{current_attempt}" self.evaluations[eval_id] = MilestoneEvaluation( evaluation_id=eval_id, grant_id=grant_id, milestone_index=milestone_index, verdict=verdict, deliverable_score=u8(deliverable_score), git_verified=git_verified, ci_verified=ci_verified, deployment_verified=deployment_verified, anti_gaming_passed=anti_gaming_passed, code_grounding_summary=grounding_summary, remediation_instructions=remediation_instructions, evaluated_at=gl.message_raw.get("datetime", ""), ) milestone.status = verdict milestone.attempt_count = u8(current_attempt) if verdict == MILESTONE_APPROVED: milestone.approved_at = gl.message_raw.get("datetime", "") all_done = True for m in grant.milestones: if m.status != MILESTONE_APPROVED: all_done = False break if all_done: grant.status = STATUS_COMPLETED return verdict def _run_consensus_evaluation( self, repo_owner: str, repo_name: str, commit_sha: str, deployment_url: str, submission_notes: str, milestone_title: str, milestone_specs: str, req_ci: bool, req_deploy: bool, ) -> dict: github_commit_url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/commits/{commit_sha}" headers = {"User-Agent": "GenLayer-ProofOfShip/1.0", "Accept": "application/json"} def leader_fn() -> dict: git_verified = False commit_msg = "" changed_files: list[str] = [] try: git_res = gl.nondet.web.get(github_commit_url, headers=headers) if git_res.status == 200: parsed_git = _parse_github_commit_response(git_res.body.decode("utf-8")) git_verified = parsed_git["valid"] commit_msg = parsed_git["message"] changed_files = parsed_git.get("changed_filenames", []) elif 400 <= git_res.status < 500: git_verified = False else: raise gl.vm.UserError(f"{ERROR_TRANSIENT} GitHub API temporary status {git_res.status}") except gl.vm.UserError: raise except Exception: git_verified = False ci_verified = True if req_ci: ci_verified = git_verified deployment_verified = True live_status = 200 live_body_excerpt = "" if req_deploy and deployment_url: try: deploy_res = gl.nondet.web.get(deployment_url, headers={"User-Agent": "GenLayer-Audit/1.0"}) live_status = deploy_res.status if deploy_res.status == 200: deployment_verified = True live_body_excerpt = deploy_res.body.decode("utf-8")[:400] else: deployment_verified = False live_body_excerpt = f"HTTP Error {deploy_res.status}" except Exception: deployment_verified = False live_status = 500 live_body_excerpt = "Connection failed" prompt = _build_evaluation_prompt( milestone_title=milestone_title, milestone_specs=milestone_specs, submission_notes=submission_notes, commit_sha=commit_sha, commit_message=commit_msg, changed_filenames=changed_files, live_status_code=live_status, live_response_snippet=live_body_excerpt, ) raw_ai = gl.nondet.exec_prompt(prompt, response_format="json") ai_eval = _parse_llm_evaluation(raw_ai) verdict = _compute_verdict( score=ai_eval["deliverable_score"], anti_gaming_passed=ai_eval["anti_gaming_passed"], git_ok=git_verified, ci_ok=ci_verified, deploy_ok=deployment_verified, ) return { "verdict": verdict, "deliverable_score": ai_eval["deliverable_score"], "git_verified": git_verified, "ci_verified": ci_verified, "deployment_verified": deployment_verified, "anti_gaming_passed": ai_eval["anti_gaming_passed"], "code_grounding_summary": ai_eval["code_grounding_summary"], "remediation_instructions": ai_eval["remediation_instructions"], } def validator_fn(leader_result: typing.Any) -> bool: if not isinstance(leader_result, gl.vm.Return): return _handle_leader_error(leader_result, leader_fn) my_eval = leader_fn() their_eval = leader_result.calldata if not isinstance(their_eval, dict): return False if their_eval.get("git_verified") != my_eval["git_verified"]: return False if their_eval.get("ci_verified") != my_eval["ci_verified"]: return False if their_eval.get("deployment_verified") != my_eval["deployment_verified"]: return False if their_eval.get("anti_gaming_passed") != my_eval["anti_gaming_passed"]: return False if their_eval.get("verdict") != my_eval["verdict"]: return False their_score = int(their_eval.get("deliverable_score", 0)) my_score = int(my_eval["deliverable_score"]) score_diff = abs(their_score - my_score) if score_diff > MAX_SCORE_DRIFT_TOLERANCE: return False return True return gl.vm.run_nondet_unsafe(leader_fn, validator_fn) # ---------------------------------------------------------------------------------- # Escrow Release & Settlement # ---------------------------------------------------------------------------------- @gl.public.write def release_milestone_funds(self, grant_id: str, milestone_index: u32) -> u256: """Release escrow funds to grantee for an approved milestone.""" grant = self._require_grant(grant_id) if milestone_index >= len(grant.milestones): raise gl.vm.UserError(f"{ERROR_EXPECTED} Invalid milestone index: {milestone_index}") milestone = grant.milestones[milestone_index] if milestone.status != MILESTONE_APPROVED: raise gl.vm.UserError(f"{ERROR_EXPECTED} Milestone is not approved: status is {milestone.status}") payout = milestone.payout_amount_wei if payout <= 0: raise gl.vm.UserError(f"{ERROR_EXPECTED} No payout remaining for this milestone") milestone.payout_amount_wei = u256(0) grant.paid_amount_wei = u256(grant.paid_amount_wei + payout) self.total_escrow_paid_wei = u256(self.total_escrow_paid_wei + payout) return payout @gl.public.write def cancel_grant(self, grant_id: str) -> u256: """Cancel an uncompleted grant and refund unreleased funds to grantor.""" grant = self._require_grant(grant_id) if grant.grantor != gl.message.sender_address: raise gl.vm.UserError(f"{ERROR_EXPECTED} Only grantor can cancel grant") if grant.status == STATUS_COMPLETED or grant.status == STATUS_CANCELLED: raise gl.vm.UserError(f"{ERROR_EXPECTED} Grant already concluded") unreleased_refund = u256(grant.funded_amount_wei - grant.paid_amount_wei) grant.status = STATUS_CANCELLED return unreleased_refund # ---------------------------------------------------------------------------------- # Internal Helpers # ---------------------------------------------------------------------------------- def _require_grant(self, grant_id: str) -> Grant: if grant_id not in self.grants: raise gl.vm.UserError(f"{ERROR_EXPECTED} Grant not found: {grant_id}") return self.grants[grant_id] # ---------------------------------------------------------------------------------- # Public View & Query Surface # ---------------------------------------------------------------------------------- @gl.public.view def get_grant_summary(self, grant_id: str) -> typing.Any: """High-level summary of grant escrow state for external composability.""" grant = self._require_grant(grant_id) return { "grant_id": str(grant.grant_id), "title": str(grant.title), "grantor": str(grant.grantor), "grantee": str(grant.grantee), "repo": f"{str(grant.repo_owner)}/{str(grant.repo_name)}", "total_budget_wei": int(grant.total_budget_wei), "funded_amount_wei": int(grant.funded_amount_wei), "paid_amount_wei": int(grant.paid_amount_wei), "status": str(grant.status), "milestone_count": len(grant.milestones), } @gl.public.view def get_milestone_status(self, grant_id: str, milestone_index: u32) -> typing.Any: """Query status and delivery state for a specific milestone.""" grant = self._require_grant(grant_id) if milestone_index >= len(grant.milestones): raise gl.vm.UserError(f"{ERROR_EXPECTED} Invalid milestone index") m = grant.milestones[milestone_index] sub_key = f"{grant_id}:{milestone_index}" has_sub = sub_key in self.submissions sub = self.submissions[sub_key] if has_sub else None return { "milestone_index": int(m.milestone_index), "title": str(m.title), "description": str(m.description), "deliverable_specs": str(m.deliverable_specs), "payout_amount_wei": int(m.payout_amount_wei), "required_ci_passing": bool(m.required_ci_passing), "required_live_deployment": bool(m.required_live_deployment), "status": str(m.status), "attempt_count": int(m.attempt_count), "approved_at": str(m.approved_at), "submission": { "commit_sha": str(sub.commit_sha) if sub else "", "pull_request_url": str(sub.pull_request_url) if sub else "", "deployment_url": str(sub.deployment_url) if sub else "", "submission_notes": str(sub.submission_notes) if sub else "", "submitted_at": str(sub.submitted_at) if sub else "", } if sub else None, } @gl.public.view def get_evaluation_record(self, evaluation_id: str) -> typing.Any: """Query consensus audit logs and remediation feedback for a specific evaluation.""" if evaluation_id not in self.evaluations: raise gl.vm.UserError(f"{ERROR_EXPECTED} Evaluation not found: {evaluation_id}") ev = self.evaluations[evaluation_id] return { "evaluation_id": str(ev.evaluation_id), "grant_id": str(ev.grant_id), "milestone_index": int(ev.milestone_index), "verdict": str(ev.verdict), "deliverable_score": int(ev.deliverable_score), "git_verified": bool(ev.git_verified), "ci_verified": bool(ev.ci_verified), "deployment_verified": bool(ev.deployment_verified), "anti_gaming_passed": bool(ev.anti_gaming_passed), "code_grounding_summary": str(ev.code_grounding_summary), "remediation_instructions": str(ev.remediation_instructions), "evaluated_at": str(ev.evaluated_at), } @gl.public.view def list_all_grants(self) -> typing.Any: """List all registered grant IDs in storage.""" return [str(gid) for gid in self.grant_ids]