# { "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. Architectural Guarantees ------------------------ - Determinism Boundary: Web and LLM calls occur strictly inside non-deterministic closures; state transitions, escrow accounting, and penalty rules execute deterministically. - Error Classification: Canonical error tags ([EXPECTED], [EXTERNAL], [TRANSIENT], [LLM_ERROR]) prevent validator split on deterministic vs transient failures. - Composability: External DAO charters and escrow contracts can query `get_milestone_status` or `get_grant_summary` to gate treasury releases. """ 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 Enums # -------------------------------------------------------------------------------------- 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 block timestamp string @allow_storage @dataclass class DeliverySubmission: """A developer's delivery submission for a milestone.""" 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] submissions: TreeMap[str, DeliverySubmission] # Key: str(milestone_index) # -------------------------------------------------------------------------------------- # Pure Helpers — Deterministic & Auditable on All Nodes # -------------------------------------------------------------------------------------- def _normalize_str(text: str) -> str: """Normalize text for consistent comparison.""" return " ".join(text.split()).casefold() def _parse_github_commit_response(raw_body: str) -> dict: """ Deterministically parse GitHub Commit API JSON response. Extracts commit existence, message, and stats without non-deterministic metadata. """ try: data = json.loads(raw_body) except Exception: return {"valid": False, "message": "", "files_changed": 0} if not isinstance(data, dict) or "sha" not in data: return {"valid": False, "message": "", "files_changed": 0} 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 # Extract file paths and patch excerpts for evidence grounding changed_filenames = [] if isinstance(files, list): for f in files[:20]: # Limit to top 20 files to bound context 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: """ Construct the substantive milestone evaluation prompt. Fences untrusted submission data and forces a constrained JSON schema. """ 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: """ Defensively parse the LLM evaluation response with type coercion and key aliasing. """ if isinstance(raw_response, str): try: # Strip markdown fences if present 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") # Score extraction with aliasing 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}") # Anti-gaming flag extraction raw_anti_gaming = raw_response.get("anti_gaming_passed", True) anti_gaming_passed = bool(raw_anti_gaming) # Text fields 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: """ Deterministic rule engine for computing the milestone verdict. Executes in pure contract logic identically on every validator node. """ # Hard infrastructure gate 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: """ Consensus error handler: deterministic errors must match exactly, transient errors agree if both fail transiently, LLM errors disagree to force leader rotation. """ leader_msg = getattr(leader_result, "message", "") or "" try: leader_fn() return False # Validator succeeded while leader failed -> disagree 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] grant_ids: DynArray[str] evaluations: TreeMap[str, MilestoneEvaluation] 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, ) -> None: """ 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=[], submissions=TreeMap(), ) 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. Only callable by the grantor. """ 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) -> None: """ 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, ) -> None: """ 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 = str(milestone_index) grant.submissions[key] = DeliverySubmission( 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. Verifies Git/CI/Deployment endpoints and evaluates code deliverable fulfillment. """ 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") key = str(milestone_index) if key not in grant.submissions: raise gl.vm.UserError(f"{ERROR_EXPECTED} No submission found for milestone {milestone_index}") submission = grant.submissions[key] # Lift storage values into plain Python 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 # Run non-deterministic consensus pipeline 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", ""), ) # Update milestone state milestone.status = verdict milestone.attempt_count = u8(current_attempt) if verdict == MILESTONE_APPROVED: milestone.approved_at = gl.message_raw.get("datetime", "") # Check if all milestones completed 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: """ Executes multi-validator consensus using custom validator equivalence checks. """ 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: # 1. Probe GitHub Commit API 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 # 2. Check CI status if required ci_verified = True if req_ci: # Satisfied if commit is valid in mock/direct mode ci_verified = git_verified # 3. Probe Live Deployment Endpoint if required 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" # 4. LLM Substantive Deliverable Audit 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) # 5. Compute Deterministic Verdict 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) # Independent verification: validator performs independent audit my_eval = leader_fn() their_eval = leader_result.calldata if not isinstance(their_eval, dict): return False # Strict Equivalence on Deterministic & Infrastructure Facts 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 # Strict Equivalence on Milestone Verdict if their_eval.get("verdict") != my_eval["verdict"]: return False # Bounded Tolerance on Qualitative Deliverable Score 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") # Zero out milestone payout to prevent double release 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. Only grantor may cancel, and only unapproved milestone funds are returned. """ 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) -> dict: """ 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) -> dict: """ 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] submission_key = str(milestone_index) has_sub = submission_key in grant.submissions sub = grant.submissions[submission_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) -> dict: """ 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) -> list: """ List all registered grant IDs in storage. """ return [str(gid) for gid in self.grant_ids]