# v0.2.16 # { "Depends": "py-genlayer:1jb45aa8ynh2a9c9xn3b7qqh8sm5q93hwfp7jqmwsfhh8jpz09h6" } import datetime import json import typing from dataclasses import dataclass from genlayer import * # ============================================================================ # SECTION 1: STATUS CONSTANTS # ============================================================================ # GenVM storage does not support Python's `enum.Enum` for persisted fields, # so status values are plain module-level integer constants stored in `u8` # fields. Keeping them as named constants (instead of magic numbers scattered # through the code) is what actually keeps a 2000+ line state machine # reviewable. # --- Job.status --- JOB_OPEN: int = 0 """Job created, at least one milestone may exist, no freelancer assigned yet.""" JOB_ACCEPTED: int = 1 """A freelancer has accepted the job and work is in progress.""" JOB_COMPLETED: int = 2 """Every milestone has reached a terminal state (PAID or REFUNDED).""" JOB_CANCELLED: int = 3 """Client cancelled before a freelancer accepted; all escrow refunded.""" JOB_STATUS_LABELS: typing.Final[dict[int, str]] = { JOB_OPEN: "OPEN", JOB_ACCEPTED: "ACCEPTED", JOB_COMPLETED: "COMPLETED", JOB_CANCELLED: "CANCELLED", } # --- Milestone.status --- MS_PENDING: int = 0 """Milestone funded and waiting for the freelancer to submit a deliverable.""" MS_SUBMITTED: int = 1 """Freelancer has submitted a deliverable URL; awaiting AI verification.""" MS_NEEDS_REVISION: int = 2 """AI consensus verdict asked for changes; freelancer may resubmit.""" MS_APPROVED: int = 3 """AI consensus verdict approved the deliverable (transient, becomes PAID).""" MS_PAID: int = 4 """Terminal: escrow released to the freelancer (minus the platform fee).""" MS_REJECTED_FINAL: int = 5 """Revision cap exhausted with no approval; client may claim a refund.""" MS_DISPUTED: int = 6 """Either party contested the AI verdict; awaiting arbiter resolution.""" MS_REFUNDED: int = 7 """Terminal: escrow returned to the client.""" MS_CANCELLED: int = 8 """Terminal: milestone cancelled before any freelancer submission.""" MS_STATUS_LABELS: typing.Final[dict[int, str]] = { MS_PENDING: "PENDING", MS_SUBMITTED: "SUBMITTED", MS_NEEDS_REVISION: "NEEDS_REVISION", MS_APPROVED: "APPROVED", MS_PAID: "PAID", MS_REJECTED_FINAL: "REJECTED_FINAL", MS_DISPUTED: "DISPUTED", MS_REFUNDED: "REFUNDED", MS_CANCELLED: "CANCELLED", } # States a milestone must be in for its escrow to still be "live" (i.e. not # yet paid out, refunded, or cancelled). Used repeatedly to guard timeout / # dispute / cancellation paths so a terminal milestone can never be touched # twice. _MS_LIVE_STATES: typing.Final[tuple[int, ...]] = ( MS_PENDING, MS_SUBMITTED, MS_NEEDS_REVISION, MS_REJECTED_FINAL, MS_DISPUTED, ) _MS_TERMINAL_STATES: typing.Final[tuple[int, ...]] = ( MS_PAID, MS_REFUNDED, MS_CANCELLED, ) # --- Verdicts returned by the AI consensus check --- VERDICT_APPROVED: str = "APPROVED" VERDICT_REJECTED: str = "REJECTED" VERDICT_NEEDS_REVISION: str = "NEEDS_REVISION" VERDICT_PARTIAL: str = "PARTIAL" """The deliverable substantially, but incompletely, satisfies the criteria -- e.g. 3 of 4 required sub-tasks are done. Rather than forcing a binary approve/reject (which either overpays for incomplete work or fully burns a freelancer's real partial progress), the verifier may recommend a split payout via `payout_bps` (see `_collect_ai_verdict`).""" _VALID_VERDICTS: typing.Final[tuple[str, ...]] = ( VERDICT_APPROVED, VERDICT_REJECTED, VERDICT_NEEDS_REVISION, VERDICT_PARTIAL, ) # --- Arbiter override verdicts --- ARBITER_APPROVE: str = "APPROVE" ARBITER_REJECT: str = "REJECT" _VALID_ARBITER_VERDICTS: typing.Final[tuple[str, ...]] = ( ARBITER_APPROVE, ARBITER_REJECT, ) # ============================================================================ # SECTION 2: PROTOCOL-WIDE CONSTANTS # ============================================================================ MAX_FEE_BPS: int = 2000 """Hard ceiling on the platform fee: 2000 basis points = 20%. Prevents an owner from ever configuring a fee that would confiscate most of a payout.""" BPS_DENOMINATOR: int = 10_000 """Basis-point denominator used for fee and partial-payout math.""" PAYOUT_BUCKET_BPS: int = 500 """Bucket width (5 percentage points) that a PARTIAL verdict's `payout_bps` is rounded onto before it is ever compared across validators or used to compute an actual payout -- see `_bucket_payout_bps` and the comment in `_collect_ai_verdict`. This is what lets the equivalence principle require an EXACT match on the paid split instead of a tolerance window: independent LLM estimates that are close collapse onto the same discrete bucket, so "close enough" and "identical" become the same thing by construction. 500 bps gives 20 possible split points (5%, 10%, ..., 95%) -- coarse enough that independent runs reliably converge, fine enough to still mean something as a partial-credit signal.""" DEFAULT_MAX_REVISIONS: int = 3 """How many NEEDS_REVISION cycles a milestone gets by default before it is marked REJECTED_FINAL and becomes refundable, absent a dispute/override.""" MIN_MILESTONE_DEADLINE_SECONDS: int = 3600 """A milestone deadline must be at least one hour out from creation, so a client cannot create a job that is immediately claimable via timeout.""" ARBITER_GRACE_SECONDS: int = 3 * 24 * 3600 """Extra grace period past a job's deadline before either party may force a default (refund-to-client) resolution on a milestone stuck in DISPUTED with no arbiter action. This is the "stuck/abandoned" recovery exit: it guarantees funds are never permanently locked just because a named arbiter goes silent.""" MAX_LISTING_SCAN: int = 200 """Upper bound on how many job ids a single view-call will scan when listing jobs, so a view method can never be made to loop unboundedly as the protocol grows. Pagination is via `start_id` / `limit` parameters.""" def _bucket_payout_bps(bps: int) -> int: """ Round a PARTIAL-verdict payout percentage onto the coarse, discrete grid defined by `PAYOUT_BUCKET_BPS`, clamped to a valid, non-degenerate fraction (never exactly 0% or exactly 100% -- those aren't "partial"). This is a pure, deterministic function of its input: every validator calling it on their own independently-estimated `payout_bps` gets the same bucketed output whenever their raw estimates are close, which is precisely what lets `_collect_ai_verdict`'s equivalence principle require an EXACT match on the bucketed value instead of a tolerance window on the raw one. Without this, the leader's exact (un-agreed) `payout_bps` would directly control the actual escrow split while validators only checked it was "close enough" to their own number -- a gap between what's compared and what's paid that a leader could exploit. Bucketing first closes that gap: the value compared for consensus and the value used for payout become the same number. """ bps = max(0, min(int(bps), BPS_DENOMINATOR)) bucketed = int(round(bps / PAYOUT_BUCKET_BPS)) * PAYOUT_BUCKET_BPS # Never let rounding produce a degenerate 0% or 100% "partial" split. bucketed = max(PAYOUT_BUCKET_BPS, min(bucketed, BPS_DENOMINATOR - PAYOUT_BUCKET_BPS)) return bucketed # ============================================================================ # SECTION 3: STORAGE-COMPATIBLE DATA STRUCTURES # ============================================================================ # Every struct that lives in a `TreeMap` value must be a `@dataclass` # decorated with `@allow_storage` (GenVM's marker that the class was # deliberately reviewed for storage use -- plain, undecorated classes are # rejected so that a developer can never accidentally rely on Python # reference semantics for something that is actually a materialized, # zero-initialized on-chain slot). @allow_storage @dataclass class Milestone: """ One unit of escrowed, independently-verifiable work inside a Job. Money accounting note: `amount` is the agreed term, `deposited` is the actual live ledger balance for this milestone. They start equal (a milestone can only be created by depositing exactly `amount`) and `deposited` is zeroed by every payout/refund path *before* any value leaves the contract -- see the module docstring's "HOW ESCROW IS IMPLEMENTED" section for why this ordering matters. """ milestone_key: u256 """Global identifier: `job_id * 10_000 + index_within_job`. Composite keys let every milestone live in one flat `TreeMap` without nesting a generic collection inside a storage struct, which keeps allocation simple and avoids the `inmem_allocate` machinery entirely.""" job_id: u256 index: u256 """Position of this milestone within its job's milestone list, 0-based.""" title: str description: str """Human-readable description of what "done" looks like for reviewers reading the contract state directly (e.g. a block explorer).""" acceptance_criteria: str """The exact criteria fed to the AI verifier. Written by the client at creation time; kept separate from `description` so a client can phrase the human summary loosely while keeping the machine-checked criteria precise.""" amount: u256 """Agreed payment term for this milestone, in the chain's native unit.""" deposited: u256 """Live escrow ledger for this milestone. Authoritative for all payout math; always zeroed before a transfer is attempted.""" status: u8 deliverable_url: str """The freelancer's most recently submitted evidence URL.""" revision_count: u8 max_revisions: u8 last_verdict: str """Most recent AI consensus verdict string (APPROVED / REJECTED / NEEDS_REVISION), empty until the first verification pass.""" last_reasoning: str """Short justification text returned by the AI verifier for the most recent verdict, truncated to a bounded length before being stored.""" disputed_by: Address dispute_reason: str created_at: u256 submitted_at: u256 resolved_at: u256 resolved_by_arbiter: bool """True if the terminal state was reached via arbiter override rather than the AI consensus path -- useful for reviewers auditing how often arbitration was actually needed.""" @allow_storage @dataclass class Job: """A client's engagement with a freelancer, made of one or more Milestones.""" job_id: u256 client: Address freelancer: Address """Zero-address (`Address("0x0000000000000000000000000000000000000000")`) until a freelancer calls `accept_job`.""" arbiter: Address """Trusted third party named by the client at creation time who can override a disputed milestone's outcome. May equal the client's own address if the client wants to self-arbitrate low-stakes jobs, but may never equal the zero address (see `create_job`'s validation).""" title: str description: str status: u8 milestone_count: u256 milestones_paid: u256 milestones_refunded: u256 milestones_cancelled: u256 total_deposited: u256 """Running sum of every milestone's `amount` at creation time, purely informational (for `get_job` summaries); payout math never reads this, it always reads the individual milestone's own `deposited` field.""" total_released: u256 """Running sum of everything actually paid out to the freelancer so far (net of fees), across all of this job's milestones.""" total_refunded: u256 platform_fee_bps: u256 """Fee rate captured at job-creation time so a later owner fee change never retroactively affects an in-flight job.""" required_bond: u256 """Performance bond the client requires from whoever accepts this job, set at creation time. Zero means no bond is required. See the "PERFORMANCE BOND" section of the module docstring for why this exists as a second, independent escrow instrument alongside per-milestone payments.""" bond_deposited: u256 """Live ledger for the freelancer's bond, separate from any milestone's `deposited` field. Zero once the bond has been returned or forfeited.""" bond_settled: bool """True once the bond has reached a terminal outcome (returned or forfeited), so it can never be double-claimed.""" deadline: u256 """Unix timestamp. After this point (plus `ARBITER_GRACE_SECONDS` for disputed milestones), unresolved live milestones become claimable via the timeout recovery paths.""" created_at: u256 @allow_storage @dataclass class Reputation: """Simple on-chain track record for an address across every job it has touched as either a client or a freelancer. Deliberately minimal -- this is a primitive other contracts/front-ends can read and build scoring or gating logic on top of, not a full reputation system itself. """ jobs_as_client: u256 jobs_as_freelancer: u256 milestones_completed: u256 """Milestones this address was paid out for, as a freelancer.""" milestones_disputed: u256 """Milestones this address was on either side of a dispute for.""" milestones_cancelled_or_refunded: u256 """Milestones that ended in a refund back to this address as a client, or that this address (as freelancer) failed to complete.""" total_earned: u256 """Net GEN received across all completed milestones, as a freelancer.""" total_paid_out: u256 """Gross GEN sent into escrow across all jobs, as a client.""" # ============================================================================ # SECTION 4: NATIVE VALUE TRANSFER # ============================================================================ # GenVM contracts do not have a built-in "send native token" statement, and # on this pinned runner there are two superficially similar but NOT # interchangeable mechanisms for moving value to another address: # # * `gl.get_contract_at(address).emit_transfer(value=...)` -- GenVM's own # native intelligent-contract-to-intelligent-contract message path. It # does NOT settle a real, externally-visible balance for a plain # externally-owned wallet (a MetaMask-style EOA): calling it against an # ordinary wallet address fails with "Contract

not found", # confirmed empirically against a live deployment. # * `@gl.evm.contract_interface` + a stub's `.emit_transfer(...)` routes # through the EVM-compatibility bridge instead, and is the mechanism # that actually delivers value to a plain wallet address. This is the # documented pattern in GenLayer's own `faucet.py` reference example # (which exists specifically to pay arbitrary requesting wallets), and # is confirmed working against a live deployment here too. # # Every payout in this contract goes to a job's client/freelancer/treasury -- # ordinary wallet addresses, not other deployed contracts -- so the EVM # bridge path is the correct one. Routing every transfer through the single # `_send_gen` helper below is deliberate: it means every place this # contract's balance can possibly decrease is discoverable by grepping for # one function name, which matters a great deal for anyone auditing an # escrow contract. @gl.evm.contract_interface class _Recipient: class View: pass class Write: pass # ============================================================================ # SECTION 5: THE CONTRACT # ============================================================================ class MilestoneManager(gl.Contract): """ Escrow + AI-verified milestone payments for freelance/bounty-style work. See the module docstring at the top of this file for the full design rationale, consensus mechanism, escrow safety pattern, and state machine. This class docstring covers only what a caller needs to use it. Typical call sequence for a single-milestone job: 1. `create_job(...)` -- client, not payable 2. `add_milestone(job_id, ..., amount)` -- client, payable == amount 3. `accept_job(job_id)` -- freelancer 4. `submit_deliverable(job_id, 0, url)` -- freelancer 5. `request_verification(job_id, 0)` -- anyone (permissionless trigger) -> APPROVED: freelancer paid automatically, fee to treasury -> NEEDS_REVISION: back to step 4 (until `max_revisions` reached) -> REJECTED (final possible outcome once `max_revisions` reached): `claim_timeout_refund` or a dispute/arbiter path returns funds to client 6. Either party may call `raise_dispute(job_id, 0, reason)` at any point the milestone is not yet terminal, which freezes it for the named `arbiter` to resolve via `resolve_dispute`. """ # ------------------------------------------------------------------ # Persistent storage. See SECTION 3 for the struct definitions and # storage.mdx's rules for why these particular container types are # used (fully-instantiated TreeMap[K, V], no bare int/dict/list). # ------------------------------------------------------------------ owner: Address """Protocol admin. Can only tune the default fee, the treasury address, and the global pause flag -- it can never move escrowed funds, resolve a dispute, or otherwise touch a single job's money. That authority belongs exclusively to each job's own client/freelancer/arbiter.""" treasury: Address """Recipient of the platform fee on successful milestone payouts.""" default_fee_bps: u256 paused: bool """When true, `create_job` is disabled. Never affects any in-flight job: existing jobs can still be worked, verified, disputed, and paid out. This is a narrow circuit breaker, not an emergency-withdraw switch.""" job_counter: u256 """Next job id to assign; also doubles as "how many jobs exist" for bounded view-method iteration.""" jobs: TreeMap[u256, Job] milestones: TreeMap[u256, Milestone] """Keyed by the composite `milestone_key` (`job_id * 10_000 + index`).""" reputation: TreeMap[Address, Reputation] # ------------------------------------------------------------------ # Construction # ------------------------------------------------------------------ def __init__(self, treasury_address: str, default_fee_bps: int) -> None: """ Deploy the protocol. Args: treasury_address: hex address that receives the platform fee cut of every successful milestone payout. default_fee_bps: fee rate in basis points (1 bps = 0.01%) applied to new jobs at creation time. Must be <= MAX_FEE_BPS (2000, i.e. 20%). """ if default_fee_bps < 0 or default_fee_bps > MAX_FEE_BPS: raise gl.vm.UserError( f"default_fee_bps must be between 0 and {MAX_FEE_BPS}" ) self.owner = gl.message.sender_address self.treasury = Address(treasury_address) self.default_fee_bps = u256(default_fee_bps) self.paused = False self.job_counter = u256(0) # ================================================================== # SECTION 6: INTERNAL HELPERS # ================================================================== # None of these are decorated with @gl.public.* -- they are ordinary # methods only reachable from other methods on this contract, and exist # purely to keep the public methods below short enough to actually # review. def _now(self) -> int: """Deterministic current time as unix seconds. `gl.message_raw["datetime"]` is the transaction's own timestamp (an ISO-8601 string) as recorded by GenVM, which is what makes deadline comparisons consensus-safe -- every validator re-executing this transaction reads the same value, unlike a wall-clock read.""" return int(datetime.datetime.fromisoformat(gl.message_raw["datetime"]).timestamp()) def _zero_address(self) -> Address: return Address("0x0000000000000000000000000000000000000000") def _send_gen(self, to_address: Address, amount: u256) -> None: """ The single choke point through which native value ever leaves this contract. Every payout path in this file calls this, and only this, to move money -- see the module docstring's escrow section for why that matters for auditability. Uses the `@gl.evm.contract_interface`-declared `_Recipient` stub's `emit_transfer`, which routes through the EVM-compatibility bridge -- the mechanism that actually delivers value to a plain wallet address (confirmed against a live deployment; GenVM's own `get_contract_at(...).emit_transfer(...)` is the intelligent-contract- to-intelligent-contract path and does not settle balance for a plain EOA). This matches GenLayer's own `faucet.py` reference example, whose entire purpose is paying arbitrary requesting wallets. """ if amount <= u256(0): raise gl.vm.UserError("Transfer amount must be positive") _Recipient(to_address).emit_transfer(value=amount) def _require_not_paused(self) -> None: if self.paused: raise gl.vm.UserError("Protocol is paused for new job creation") def _require_owner(self) -> None: if gl.message.sender_address != self.owner: raise gl.vm.UserError("Caller is not the protocol owner") def _get_job(self, job_id: int) -> Job: key = u256(job_id) if key not in self.jobs: raise gl.vm.UserError(f"No job with id {job_id}") return self.jobs[key] def _milestone_key(self, job_id: int, index: int) -> u256: if index < 0 or index >= 10_000: raise gl.vm.UserError("Milestone index out of supported range") return u256(int(job_id) * 10_000 + int(index)) def _get_milestone(self, job_id: int, index: int) -> Milestone: key = self._milestone_key(job_id, index) if key not in self.milestones: raise gl.vm.UserError( f"No milestone at index {index} for job {job_id}" ) return self.milestones[key] def _require_client(self, job: Job) -> None: if gl.message.sender_address != job.client: raise gl.vm.UserError("Caller is not this job's client") def _require_freelancer(self, job: Job) -> None: if gl.message.sender_address != job.freelancer: raise gl.vm.UserError("Caller is not this job's assigned freelancer") def _require_client_or_freelancer(self, job: Job) -> None: sender = gl.message.sender_address if sender != job.client and sender != job.freelancer: raise gl.vm.UserError( "Caller is neither this job's client nor its freelancer" ) def _require_arbiter(self, job: Job) -> None: if gl.message.sender_address != job.arbiter: raise gl.vm.UserError("Caller is not this job's designated arbiter") def _get_or_create_reputation(self, address: Address) -> Reputation: if address not in self.reputation: self.reputation[address] = Reputation( jobs_as_client=u256(0), jobs_as_freelancer=u256(0), milestones_completed=u256(0), milestones_disputed=u256(0), milestones_cancelled_or_refunded=u256(0), total_earned=u256(0), total_paid_out=u256(0), ) return self.reputation[address] def _fee_and_net(self, gross: int, fee_bps: int) -> tuple[int, int]: """Split a gross payout into (fee, net_to_freelancer) using integer basis-point math. Always computed from the live ledger amount, never from the job's original `amount` term, so a fee calculation can never drift from what is actually held in escrow.""" fee = (gross * fee_bps) // BPS_DENOMINATOR return fee, gross - fee # ------------------------------------------------------------------ # Shared payout / refund primitives. Every path that moves a # milestone's escrow to a terminal state funnels through one of these # two, which is what guarantees the zero-then-transfer ordering is # applied uniformly instead of being re-implemented (and potentially # gotten wrong) at each call site. # ------------------------------------------------------------------ def _payout_milestone( self, job: Job, milestone: Milestone, via_arbiter: bool ) -> None: deposited = milestone.deposited if deposited <= u256(0): raise gl.vm.UserError("No escrowed funds remain for this milestone") # --- 1. read ledger, 2. zero ledger + persist status, BEFORE any transfer --- fee, net = self._fee_and_net(int(deposited), int(job.platform_fee_bps)) milestone.deposited = u256(0) milestone.status = u8(MS_PAID) milestone.resolved_at = u256(self._now()) milestone.resolved_by_arbiter = via_arbiter job.milestones_paid = job.milestones_paid + u256(1) job.total_released = job.total_released + u256(net) if job.milestones_paid + job.milestones_refunded + job.milestones_cancelled >= job.milestone_count: job.status = u8(JOB_COMPLETED) self._settle_bond_on_job_completion(job) freelancer_rep = self._get_or_create_reputation(job.freelancer) freelancer_rep.milestones_completed = freelancer_rep.milestones_completed + u256(1) freelancer_rep.total_earned = freelancer_rep.total_earned + u256(net) # --- 3. transfer, strictly after state is already zeroed and saved --- self._send_gen(job.freelancer, u256(net)) if fee > 0: self._send_gen(self.treasury, u256(fee)) def _payout_partial_milestone( self, job: Job, milestone: Milestone, payout_bps: int ) -> None: """ Splits a milestone's escrow between the freelancer and the client according to the AI consensus's recommended `payout_bps`, applying the platform fee only to the freelancer's share (the client's refunded share was never actually earned by anyone, so it isn't fee income). Follows the same zero-then-transfer discipline as every other payout: the full ledger is read and zeroed before either leg of the split is transferred. """ deposited = milestone.deposited if deposited <= u256(0): raise gl.vm.UserError("No escrowed funds remain for this milestone") freelancer_gross = (int(deposited) * payout_bps) // BPS_DENOMINATOR client_share = int(deposited) - freelancer_gross fee, freelancer_net = self._fee_and_net(freelancer_gross, int(job.platform_fee_bps)) # --- zero the ledger and persist status BEFORE either transfer --- milestone.deposited = u256(0) milestone.status = u8(MS_PAID) milestone.resolved_at = u256(self._now()) milestone.resolved_by_arbiter = False job.milestones_paid = job.milestones_paid + u256(1) job.total_released = job.total_released + u256(freelancer_net) job.total_refunded = job.total_refunded + u256(client_share) if job.milestones_paid + job.milestones_refunded + job.milestones_cancelled >= job.milestone_count: job.status = u8(JOB_COMPLETED) self._settle_bond_on_job_completion(job) freelancer_rep = self._get_or_create_reputation(job.freelancer) freelancer_rep.milestones_completed = freelancer_rep.milestones_completed + u256(1) freelancer_rep.total_earned = freelancer_rep.total_earned + u256(freelancer_net) # --- transfers, strictly after state is already zeroed and saved --- if freelancer_net > 0: self._send_gen(job.freelancer, u256(freelancer_net)) if fee > 0: self._send_gen(self.treasury, u256(fee)) if client_share > 0: self._send_gen(job.client, u256(client_share)) def _refund_milestone( self, job: Job, milestone: Milestone, via_arbiter: bool ) -> None: deposited = milestone.deposited if deposited <= u256(0): raise gl.vm.UserError("No escrowed funds remain for this milestone") milestone.deposited = u256(0) milestone.status = u8(MS_REFUNDED) milestone.resolved_at = u256(self._now()) milestone.resolved_by_arbiter = via_arbiter job.milestones_refunded = job.milestones_refunded + u256(1) job.total_refunded = job.total_refunded + deposited if job.milestones_paid + job.milestones_refunded + job.milestones_cancelled >= job.milestone_count: job.status = u8(JOB_COMPLETED) self._settle_bond_on_job_completion(job) client_rep = self._get_or_create_reputation(job.client) client_rep.milestones_cancelled_or_refunded = ( client_rep.milestones_cancelled_or_refunded + u256(1) ) self._send_gen(job.client, deposited) def _settle_bond_on_job_completion(self, job: Job) -> None: """ Called exactly once, at the moment a job's last live milestone reaches a terminal state and the job transitions to `JOB_COMPLETED`. Returns the freelancer's bond if at least one milestone was actually paid out (i.e. the freelancer did demonstrably deliver something); if every single milestone ended in a refund (the freelancer accepted the job, the escrow existed, but nothing was ever approved), the bond is instead forfeited to the client -- the same signal (zero successful deliveries on an accepted job) that `claim_bond_forfeiture` uses for the no-show timeout path below. Idempotent via `bond_settled`: a job can only complete once, but this guard also protects against the (otherwise impossible, but cheap to make structurally certain) case of this being invoked twice. """ if job.bond_settled: return bond = job.bond_deposited if bond <= u256(0): job.bond_settled = True return job.bond_deposited = u256(0) job.bond_settled = True if int(job.milestones_paid) > 0: self._send_gen(job.freelancer, bond) else: self._send_gen(job.client, bond) # ------------------------------------------------------------------ # The non-deterministic, consensus-checked AI verification step. # ------------------------------------------------------------------ def _collect_ai_verdict( self, title: str, description: str, criteria: str, deliverable_url: str ) -> dict: """ Fetch the freelancer's deliverable from the web and ask an LLM whether it satisfies the milestone's acceptance criteria, with the result confirmed by GenLayer validator consensus. Every argument here is a plain, already-copied-out Python primitive (str) -- never a live storage-backed object -- because storage objects cannot be read from inside a non-deterministic closure (see storage.mdx, "Storage objects need to be copied to memory when you want to use them in non-deterministic blocks"). Callers of this method are responsible for reading milestone fields into locals first, exactly as GenLayer's own `football_prediction_market.py` reference example does. """ def run_review() -> str: # `mode="text"` strips markup and returns the page as plain # text, matching the proven pattern in the football prediction # market reference example -- avoids relying on the exact shape # of a richer response object (headers/status/etc.), which can # differ across pinned GenVM runner versions. # # A dead/unreachable/404 deliverable_url must NOT crash this # whole call: an uncaught fetch exception here fails the entire # `request_verification` transaction (confirmed empirically -- # exit_code 1, no state change, milestone stuck at SUBMITTED # with no verdict recorded and no way to recover except waiting # out the job deadline). Every validator hits the same URL and # the same failure deterministically, so falling back to a # canned NEEDS_REVISION here still converges under # `prompt_comparative` -- it just skips the LLM call entirely # for this path, which is also cheaper. try: page_text = gl.nondet.web.render(deliverable_url, mode="text") except Exception as exc: return json.dumps( { "verdict": VERDICT_NEEDS_REVISION, "reasoning": f"Deliverable URL could not be fetched: {str(exc)[:200]}", "payout_bps": 0, }, sort_keys=True, ) # Keep the grounding evidence bounded so prompts stay well # within model context limits regardless of how large the # fetched page is. if len(page_text) > 12_000: page_text = page_text[:12_000] prompt = f""" You are an impartial reviewer for a freelance escrow platform. A freelancer was hired to complete the following milestone, and has submitted evidence at a URL. Your job is to decide, using ONLY the fetched web content below, and NOT any prior belief about what the page ought to contain, whether the milestone's acceptance criteria are satisfied. Milestone title: {title} Milestone description: {description} Acceptance criteria (this is the only standard to judge against): {criteria} Deliverable URL that was fetched: {deliverable_url} Fetched web page content (plain text, may be truncated): --- {page_text} --- End of fetched content. Decide one of exactly four verdicts: - "APPROVED": the fetched content clearly and fully satisfies the acceptance criteria. - "PARTIAL": the fetched content demonstrates real, substantial progress against the acceptance criteria but is not fully complete (e.g. some but not all required parts are present and working). Only use this when you can point to specific, concrete evidence of what IS done versus what is missing -- not as a vague middle ground. - "REJECTED": the fetched content clearly does NOT satisfy the acceptance criteria, shows no substantial progress, and no reasonable revision of the same submission would fix it without materially different work. - "NEEDS_REVISION": the submission might be complete but has a fixable problem (e.g. the fetched content could not be retrieved meaningfully -- an empty, broken, or clearly wrong page), and the freelancer should be given a chance to fix and resubmit rather than being scored at all yet. If you are unsure or the fetched content is empty/unreadable, prefer "NEEDS_REVISION" over "REJECTED" -- final rejection should be reserved for cases where the evidence is unambiguous. Respond using ONLY the following JSON format, nothing else. Don't include markdown code fences, commentary, or any other characters. Your output must be perfectly parsable by a JSON parser without errors: {{ "verdict": str, // exactly one of "APPROVED", "PARTIAL", "REJECTED", "NEEDS_REVISION" "reasoning": str, // one or two sentences justifying the verdict, grounded in the fetched content "payout_bps": int // ONLY meaningful when verdict is "PARTIAL": the freelancer's recommended // share of the milestone payment, in basis points out of 10000, reflecting // how much of the acceptance criteria was concretely satisfied. 0 for any // other verdict. }} """ raw_response = gl.nondet.exec_prompt(prompt) raw_response = raw_response.replace("```json", "").replace("```", "").strip() # Canonicalize `payout_bps` to a coarse, deterministic bucket # BEFORE this closure returns -- not after the equivalence # principle has already decided leader and validator agree. # # Why this matters: the leader's raw `payout_bps` is what # directly drives the actual escrow split in # `_payout_partial_milestone`. If validators only checked that # value was "close enough" to their own independent estimate # (a tolerance window) while the leader's exact, un-agreed # number was the one actually used for payout, a leader could # pick any value inside that tolerance band -- nothing forces # the *paid* amount itself to be something every validator # actually agreed to. Bucketing here, before comparison, means # every validator's independent LLM call is rounded onto the # same discrete grid; two runs whose raw estimates are close # collapse onto an identical number, and the equivalence # principle below can require an EXACT match on that number # instead of a fuzzy one -- so the value that gets compared # for consensus IS the value that gets paid out, with no gap # between them for a leader to exploit. try: parsed_for_bucket = json.loads(raw_response) if parsed_for_bucket.get("verdict") == VERDICT_PARTIAL: raw_bps = int(parsed_for_bucket.get("payout_bps", 0)) raw_bps = max(0, min(raw_bps, BPS_DENOMINATOR)) parsed_for_bucket["payout_bps"] = _bucket_payout_bps(raw_bps) raw_response = json.dumps(parsed_for_bucket, sort_keys=True) except (json.JSONDecodeError, ValueError, TypeError, AttributeError): # Leave raw_response as-is; the outer parser below already # tolerates and safely defaults malformed JSON. pass print(raw_response) return raw_response # `prompt_comparative`: every validator independently re-fetches the # URL and re-runs the prompt themselves (they do not just check the # leader's JSON is well-formed). The equivalence rule below tells # them exactly what must match exactly vs. what may vary in wording # -- this is what turns an LLM call into a genuine consensus verdict # rather than a single node's unverified opinion. `payout_bps` is # now bucketed onto a coarse, discrete grid inside `run_review` # (see the comment there) before this comparison ever runs, so # requiring an EXACT match on it here is both achievable (natural # LLM noise collapses onto the same bucket) and necessary (it is # the bucketed value, not some looser approximation of it, that # `request_verification` actually pays out). result = gl.eq_principle.prompt_comparative( run_review, principle=( "The `verdict` field must be EXACTLY the same string. " "The `reasoning` field may differ in wording as long as it " "supports the same verdict and is grounded in the fetched " "page content rather than contradicting it. When `verdict` " 'is "PARTIAL", the `payout_bps` field must be EXACTLY the ' "same integer in both results (it has already been rounded " "onto a coarse discrete bucket, so it is not expected to " "vary); otherwise `payout_bps` is not compared." ), ) parsed = json.loads(result) verdict = parsed.get("verdict", "") if verdict not in _VALID_VERDICTS: # A validator set that reaches consensus on a malformed verdict # should not be able to silently no-op a milestone forever -- # treat it the same as an explicit request for another attempt. verdict = VERDICT_NEEDS_REVISION reasoning = str(parsed.get("reasoning", ""))[:500] payout_bps = 0 if verdict == VERDICT_PARTIAL: try: payout_bps = int(parsed.get("payout_bps", 0)) except (TypeError, ValueError): payout_bps = 0 # Clamp defensively: a PARTIAL verdict must never be able to pay # out more than 100% or less than 0%, regardless of what the # model returned. payout_bps = max(0, min(payout_bps, BPS_DENOMINATOR)) if payout_bps <= 0 or payout_bps >= BPS_DENOMINATOR: # A "partial" payout of 0% or 100% isn't actually partial; # fall back to the unambiguous binary verdicts instead of # letting a degenerate split verdict through. verdict = VERDICT_REJECTED if payout_bps <= 0 else VERDICT_APPROVED return {"verdict": verdict, "reasoning": reasoning, "payout_bps": payout_bps} # ================================================================== # SECTION 7: PUBLIC WRITE METHODS -- JOB LIFECYCLE # ================================================================== @gl.public.write def create_job( self, title: str, description: str, arbiter_address: str, deadline_seconds_from_now: int, required_bond: int, ) -> int: """ Create a new job shell (no milestones or escrow yet). The caller becomes the job's client. Returns the new job id. Args: title: short human-readable job name. description: longer description of the overall engagement. arbiter_address: hex address of a trusted third party who can resolve disputes on this job's milestones. May be the client's own address for self-arbitrated jobs, but may not be the zero address. deadline_seconds_from_now: how many seconds from now this job's milestones remain protected before timeout-recovery paths become available. Must be at least `MIN_MILESTONE_DEADLINE_SECONDS`. required_bond: performance bond, in native units, that whoever accepts this job must escrow via `accept_job`. Pass 0 to require no bond. See the module docstring's "PERFORMANCE BOND" section. """ self._require_not_paused() if required_bond < 0: raise gl.vm.UserError("required_bond must not be negative") if not title: raise gl.vm.UserError("Job title must not be empty") if deadline_seconds_from_now < MIN_MILESTONE_DEADLINE_SECONDS: raise gl.vm.UserError( f"deadline_seconds_from_now must be >= {MIN_MILESTONE_DEADLINE_SECONDS}" ) arbiter = Address(arbiter_address) if arbiter == self._zero_address(): raise gl.vm.UserError("Arbiter address must not be the zero address") now = self._now() job_id = self.job_counter self.job_counter = self.job_counter + u256(1) client = gl.message.sender_address self.jobs[job_id] = Job( job_id=job_id, client=client, freelancer=self._zero_address(), arbiter=arbiter, title=title, description=description, status=u8(JOB_OPEN), milestone_count=u256(0), milestones_paid=u256(0), milestones_refunded=u256(0), milestones_cancelled=u256(0), total_deposited=u256(0), total_released=u256(0), total_refunded=u256(0), platform_fee_bps=self.default_fee_bps, required_bond=u256(required_bond), bond_deposited=u256(0), bond_settled=(required_bond == 0), deadline=u256(now + deadline_seconds_from_now), created_at=u256(now), ) client_rep = self._get_or_create_reputation(client) client_rep.jobs_as_client = client_rep.jobs_as_client + u256(1) return int(job_id) @gl.public.write.payable def add_milestone( self, job_id: int, title: str, description: str, acceptance_criteria: str, amount: int, ) -> int: """ Add a milestone to a job and escrow its payment in the same transaction. `gl.message.value` MUST equal `amount` exactly -- this contract never accepts "at least" a deposit, since silently over-accepting would create an unaccounted-for balance and under-accepting would break the ledger-equals-terms invariant every payout path relies on. Only the job's client may call this, and only while the job is still OPEN or ACCEPTED (milestones may be added incrementally as work progresses, not just up front). Returns the new milestone's index within the job. """ job = self._get_job(job_id) self._require_client(job) if job.status not in (JOB_OPEN, JOB_ACCEPTED): raise gl.vm.UserError( "Cannot add milestones to a job that is completed or cancelled" ) if not title or not acceptance_criteria: raise gl.vm.UserError( "Milestone title and acceptance_criteria must not be empty" ) if amount <= 0: raise gl.vm.UserError("Milestone amount must be positive") deposit = gl.message.value if int(deposit) != int(amount): raise gl.vm.UserError( "Sent value must exactly equal the milestone amount " f"(expected {amount}, got {int(deposit)})" ) index = int(job.milestone_count) key = self._milestone_key(job_id, index) now = self._now() self.milestones[key] = Milestone( milestone_key=key, job_id=u256(job_id), index=u256(index), title=title, description=description, acceptance_criteria=acceptance_criteria, amount=u256(amount), deposited=deposit, status=u8(MS_PENDING), deliverable_url="", revision_count=u8(0), max_revisions=u8(DEFAULT_MAX_REVISIONS), last_verdict="", last_reasoning="", disputed_by=self._zero_address(), dispute_reason="", created_at=u256(now), submitted_at=u256(0), resolved_at=u256(0), resolved_by_arbiter=False, ) job.milestone_count = job.milestone_count + u256(1) job.total_deposited = job.total_deposited + deposit client_rep = self._get_or_create_reputation(job.client) client_rep.total_paid_out = client_rep.total_paid_out + deposit return index @gl.public.write.payable def accept_job(self, job_id: int) -> None: """ Claim a job as its freelancer. Requires the job to be OPEN, have at least one funded milestone, and not already have a freelancer. A job may only ever have one freelancer for its whole lifetime -- this primitive does not support reassigning a job mid-flight; a client who needs that should cancel remaining unpaid milestones and open a new job. If the job was created with a non-zero `required_bond`, `gl.message.value` MUST equal it exactly (same "exact match, never 'at least'" rule `add_milestone` uses, and for the same reason: an exact match is what keeps the ledger field trustworthy). If `required_bond` is zero, sending any value here is rejected, so a freelancer can never accidentally strand funds in a job that has no bond mechanism to account for them. """ job = self._get_job(job_id) if job.status != JOB_OPEN: raise gl.vm.UserError("Job is not open for acceptance") if job.freelancer != self._zero_address(): raise gl.vm.UserError("Job already has an assigned freelancer") if job.milestone_count == u256(0): raise gl.vm.UserError("Job has no funded milestones yet") if self._now() >= int(job.deadline): raise gl.vm.UserError( "Job deadline has already passed; it can no longer be accepted" ) sender = gl.message.sender_address if sender == job.client: raise gl.vm.UserError("A job's client cannot also be its freelancer") sent = gl.message.value if int(sent) != int(job.required_bond): raise gl.vm.UserError( "Sent value must exactly equal this job's required_bond " f"(expected {int(job.required_bond)}, got {int(sent)})" ) job.freelancer = sender job.status = u8(JOB_ACCEPTED) if int(job.required_bond) > 0: job.bond_deposited = sent job.bond_settled = False freelancer_rep = self._get_or_create_reputation(sender) freelancer_rep.jobs_as_freelancer = freelancer_rep.jobs_as_freelancer + u256(1) @gl.public.write def cancel_job(self, job_id: int) -> None: """ Cancel a job and refund every still-live milestone's escrow to the client. Only allowed while the job is OPEN (i.e. before a freelancer has accepted) -- once someone has started work, cancellation must go through the dispute/timeout paths instead, so a client cannot yank funding out from under a freelancer who has already begun. """ job = self._get_job(job_id) self._require_client(job) if job.status != JOB_OPEN: raise gl.vm.UserError( "Only an OPEN job (no freelancer yet) can be cancelled directly" ) for index in range(int(job.milestone_count)): key = self._milestone_key(job_id, index) milestone = self.milestones[key] if milestone.status not in _MS_LIVE_STATES: continue deposited = milestone.deposited if deposited <= u256(0): continue milestone.deposited = u256(0) milestone.status = u8(MS_CANCELLED) milestone.resolved_at = u256(self._now()) job.milestones_cancelled = job.milestones_cancelled + u256(1) job.total_refunded = job.total_refunded + deposited self._send_gen(job.client, deposited) job.status = u8(JOB_CANCELLED) # ================================================================== # SECTION 8: PUBLIC WRITE METHODS -- MILESTONE WORK CYCLE # ================================================================== @gl.public.write def submit_deliverable(self, job_id: int, milestone_index: int, deliverable_url: str) -> None: """ Freelancer submits (or resubmits, after a NEEDS_REVISION verdict) the URL where reviewers -- human or AI -- can see the completed work. Does not itself trigger verification; call `request_verification` afterwards (kept as two steps so a freelancer can submit without forcing the, comparatively expensive, multi-validator AI check to run in the same transaction). """ job = self._get_job(job_id) self._require_freelancer(job) milestone = self._get_milestone(job_id, milestone_index) if milestone.status not in (MS_PENDING, MS_NEEDS_REVISION): raise gl.vm.UserError( "Milestone is not awaiting a deliverable submission right now" ) if not deliverable_url: raise gl.vm.UserError("deliverable_url must not be empty") milestone.deliverable_url = deliverable_url milestone.status = u8(MS_SUBMITTED) milestone.submitted_at = u256(self._now()) @gl.public.write def request_verification(self, job_id: int, milestone_index: int) -> str: """ Trigger the non-deterministic, consensus-checked AI review of a submitted deliverable (see `_collect_ai_verdict` and the module docstring's consensus section). Deliberately permissionless -- anyone can call this once a deliverable is submitted, since the verdict is validator-checked and does not depend on who happened to trigger it, and letting either party (or an automated relayer) trigger it keeps a milestone from stalling just because one side is slow to act. Returns the verdict string ("APPROVED", "PARTIAL", "REJECTED", or "NEEDS_REVISION"). On "APPROVED", the freelancer is paid (minus the platform fee) in this same transaction. On "PARTIAL", the escrow is split between freelancer and client per the AI's recommended `payout_bps` (see `_payout_partial_milestone`) and the milestone also reaches a terminal PAID state -- a partial verdict is final, not resubmittable, since it already reflects a considered judgment of how much of the criteria were met. On a final "REJECTED" (i.e. the revision cap has already been used up), the milestone becomes REJECTED_FINAL and refundable via `claim_timeout_refund` or a dispute; it is NOT auto-refunded here, so the client has a chance to raise a dispute first if they believe the AI verdict itself was wrong. """ job = self._get_job(job_id) milestone = self._get_milestone(job_id, milestone_index) if milestone.status != MS_SUBMITTED: raise gl.vm.UserError( "Milestone must be in SUBMITTED status to request verification" ) # Copy every field the non-deterministic closure needs into plain # local variables *before* calling into it -- storage-backed objects # cannot be read from inside a nondet block (see storage.mdx). title = milestone.title description = milestone.description criteria = milestone.acceptance_criteria url = milestone.deliverable_url verdict_info = self._collect_ai_verdict(title, description, criteria, url) verdict = verdict_info["verdict"] reasoning = verdict_info["reasoning"] payout_bps = verdict_info["payout_bps"] milestone.last_verdict = verdict milestone.last_reasoning = reasoning milestone.resolved_at = u256(self._now()) if verdict == VERDICT_APPROVED: self._payout_milestone(job, milestone, via_arbiter=False) elif verdict == VERDICT_PARTIAL: self._payout_partial_milestone(job, milestone, payout_bps) elif verdict == VERDICT_NEEDS_REVISION: milestone.revision_count = u8(int(milestone.revision_count) + 1) if int(milestone.revision_count) >= int(milestone.max_revisions): # Revision budget exhausted without ever earning an # APPROVED verdict -- treat like a final rejection so the # client isn't stuck funding endless resubmission loops. milestone.status = u8(MS_REJECTED_FINAL) else: milestone.status = u8(MS_PENDING) else: # VERDICT_REJECTED milestone.status = u8(MS_REJECTED_FINAL) return verdict # ================================================================== # SECTION 9: PUBLIC WRITE METHODS -- DISPUTES & ARBITRATION # ================================================================== @gl.public.write def raise_dispute(self, job_id: int, milestone_index: int, reason: str) -> None: """ Either the client or the freelancer may contest a milestone's current outcome (or lack of one) at any point it is not already terminal. Freezes the milestone in DISPUTED status pending the named arbiter's decision via `resolve_dispute`, or, if the arbiter never acts, the timeout-based `force_default_resolution` path. """ job = self._get_job(job_id) self._require_client_or_freelancer(job) milestone = self._get_milestone(job_id, milestone_index) if milestone.status not in _MS_LIVE_STATES: raise gl.vm.UserError( "Milestone has already reached a terminal state and cannot be disputed" ) if milestone.status == MS_DISPUTED: raise gl.vm.UserError("Milestone is already under dispute") if not reason: raise gl.vm.UserError("A dispute reason must be provided") milestone.status = u8(MS_DISPUTED) milestone.disputed_by = gl.message.sender_address milestone.dispute_reason = reason disputer_rep = self._get_or_create_reputation(gl.message.sender_address) disputer_rep.milestones_disputed = disputer_rep.milestones_disputed + u256(1) @gl.public.write def resolve_dispute( self, job_id: int, milestone_index: int, verdict: str, resolution_note: str ) -> None: """ Only the job's designated arbiter may call this. Directly pays out the freelancer (`verdict == "APPROVE"`) or refunds the client (`verdict == "REJECT"`) for a milestone currently under dispute -- an arbiter's decision is final and bypasses the AI verification path entirely, since it exists specifically to handle cases the automated check got wrong or couldn't resolve. """ job = self._get_job(job_id) self._require_arbiter(job) milestone = self._get_milestone(job_id, milestone_index) if milestone.status != MS_DISPUTED: raise gl.vm.UserError("Milestone is not currently under dispute") if verdict not in _VALID_ARBITER_VERDICTS: raise gl.vm.UserError('verdict must be "APPROVE" or "REJECT"') milestone.last_reasoning = (resolution_note or "")[:500] if verdict == ARBITER_APPROVE: self._payout_milestone(job, milestone, via_arbiter=True) else: self._refund_milestone(job, milestone, via_arbiter=True) @gl.public.write def force_default_resolution(self, job_id: int, milestone_index: int) -> None: """ Stuck/abandoned-arbiter recovery path. If a milestone has been DISPUTED for longer than the job's deadline plus `ARBITER_GRACE_SECONDS` and the arbiter still hasn't called `resolve_dispute`, either the client or the freelancer may force a default resolution. The default always favors returning funds to the depositor (the client) rather than the freelancer, matching the conservative default most escrow systems use when arbitration silently fails: an unresponsive arbiter should not be exploitable to auto-drain escrow to either side. """ job = self._get_job(job_id) self._require_client_or_freelancer(job) milestone = self._get_milestone(job_id, milestone_index) if milestone.status != MS_DISPUTED: raise gl.vm.UserError("Milestone is not currently under dispute") deadline_with_grace = int(job.deadline) + ARBITER_GRACE_SECONDS if self._now() < deadline_with_grace: raise gl.vm.UserError( "Arbiter grace period has not yet elapsed for this job" ) self._refund_milestone(job, milestone, via_arbiter=False) # ================================================================== # SECTION 10: PUBLIC WRITE METHODS -- TIMEOUT RECOVERY # ================================================================== @gl.public.write def claim_timeout_refund(self, job_id: int, milestone_index: int) -> None: """ The client's guaranteed exit if a milestone is still live (not yet paid, refunded, or cancelled) once the job's deadline has passed -- covers a freelancer who never submits, or a REJECTED_FINAL milestone the client doesn't wish to dispute further. Callable by the client only; the freelancer's equivalent protection against a non-responsive client is the permissionless `request_verification` (anyone can push a submitted milestone toward payout) plus `raise_dispute` / `force_default_resolution` for anything murkier. A DISPUTED milestone is explicitly excluded: once disputed, its settlement belongs to the arbiter's `resolve_dispute` or, failing that, the post-grace-period `force_default_resolution` -- routing it through the ordinary deadline here would let a dispute be settled the moment the job deadline hits, skipping `ARBITER_GRACE_SECONDS` entirely. """ job = self._get_job(job_id) self._require_client(job) milestone = self._get_milestone(job_id, milestone_index) if milestone.status == MS_DISPUTED: raise gl.vm.UserError( "Milestone is under dispute; use resolve_dispute or, after " "the arbiter grace period, force_default_resolution" ) if milestone.status not in _MS_LIVE_STATES: raise gl.vm.UserError( "Milestone has already reached a terminal state" ) if self._now() < int(job.deadline): raise gl.vm.UserError("Job deadline has not yet passed") self._refund_milestone(job, milestone, via_arbiter=False) @gl.public.write def claim_bond_forfeiture(self, job_id: int) -> None: """ Client-only no-show recovery for the performance bond (see the module docstring's "PERFORMANCE BOND" section). If a freelancer accepted a job with a non-zero bond, the job's deadline has passed, and not a single milestone was ever even submitted (let alone approved), that is unambiguous no-show behavior distinct from any one milestone's own outcome -- so it has its own claim path rather than waiting for every milestone to individually time out. Requires: job is ACCEPTED (not yet COMPLETED/CANCELLED), the bond is unsettled, the deadline has passed, and every milestone is still in its initial PENDING state (i.e. `submit_deliverable` was never successfully called for any of them). """ job = self._get_job(job_id) self._require_client(job) if job.status != JOB_ACCEPTED: raise gl.vm.UserError("Job must be ACCEPTED for a no-show bond claim") if job.bond_settled or job.bond_deposited <= u256(0): raise gl.vm.UserError("No unsettled bond exists for this job") if self._now() < int(job.deadline): raise gl.vm.UserError("Job deadline has not yet passed") for index in range(int(job.milestone_count)): milestone = self._get_milestone(job_id, index) if milestone.status != MS_PENDING: raise gl.vm.UserError( "At least one milestone was submitted; this is not a " "clear no-show -- use per-milestone timeout/dispute " "paths instead" ) bond = job.bond_deposited job.bond_deposited = u256(0) job.bond_settled = True self._send_gen(job.client, bond) @gl.public.write def extend_milestone_revisions(self, job_id: int, milestone_index: int, extra_revisions: int) -> None: """ Client-only. Raises a milestone's `max_revisions` cap by `extra_revisions`, for cases where a client believes a freelancer is making genuine progress and wants to allow more NEEDS_REVISION cycles than the default before the milestone would otherwise become REJECTED_FINAL. Only usable while the milestone is still live (not yet in a terminal state) -- extending a cap on a milestone that has already been paid, refunded, or cancelled would have no meaning. """ job = self._get_job(job_id) self._require_client(job) if extra_revisions <= 0: raise gl.vm.UserError("extra_revisions must be positive") milestone = self._get_milestone(job_id, milestone_index) if milestone.status not in _MS_LIVE_STATES: raise gl.vm.UserError( "Cannot extend revisions on a milestone in a terminal state" ) new_cap = int(milestone.max_revisions) + extra_revisions if new_cap > 255: raise gl.vm.UserError("max_revisions cannot exceed 255 (u8 range)") milestone.max_revisions = u8(new_cap) # A REJECTED_FINAL milestone that just had its cap raised should be # given a genuine second chance to be resubmitted rather than sitting # in a state that claims no more revisions remain. if milestone.status == MS_REJECTED_FINAL: milestone.status = u8(MS_NEEDS_REVISION) @gl.public.write def extend_job_deadline(self, job_id: int, extra_seconds: int) -> None: """ Client-only. Pushes a job's deadline further into the future -- for example when a client is satisfied progress is being made and does not want timeout-recovery paths to become available yet. Can only move the deadline forward, never backward, so this method can never be used to make funds prematurely reclaimable against a freelancer's interest. """ job = self._get_job(job_id) self._require_client(job) if extra_seconds <= 0: raise gl.vm.UserError("extra_seconds must be positive") if job.status not in (JOB_OPEN, JOB_ACCEPTED): raise gl.vm.UserError("Cannot extend the deadline of a finished job") job.deadline = job.deadline + u256(extra_seconds) # ================================================================== # SECTION 11: ADMIN (OWNER-ONLY, NEVER TOUCHES ESCROWED FUNDS) # ================================================================== @gl.public.write def update_default_fee_bps(self, new_fee_bps: int) -> None: """Owner-only. Changes the fee rate captured by NEW jobs created after this call; every already-created job keeps the fee rate it was created with (`Job.platform_fee_bps`), so this can never retroactively change what an in-flight job's freelancer will net.""" self._require_owner() if new_fee_bps < 0 or new_fee_bps > MAX_FEE_BPS: raise gl.vm.UserError(f"new_fee_bps must be between 0 and {MAX_FEE_BPS}") self.default_fee_bps = u256(new_fee_bps) @gl.public.write def update_treasury(self, new_treasury_address: str) -> None: """Owner-only. Changes where future fee payouts are sent. Fees already paid to the old treasury are, obviously, unaffected.""" self._require_owner() new_treasury = Address(new_treasury_address) if new_treasury == self._zero_address(): raise gl.vm.UserError("Treasury address must not be the zero address") self.treasury = new_treasury @gl.public.write def set_paused(self, is_paused: bool) -> None: """Owner-only. Toggles whether NEW jobs can be created. Never affects any existing job's ability to progress through submission, verification, dispute, arbitration, or timeout recovery -- this is a narrow "stop taking on new work" switch, not an emergency pause over funds already in escrow.""" self._require_owner() self.paused = is_paused # ================================================================== # SECTION 12: VIEW METHODS # ================================================================== # All read-only. None of these mutate state or touch the non-deterministic # web/LLM path -- they only ever read already-settled contract storage. @gl.public.view def get_job(self, job_id: int) -> TreeMap[str, typing.Any]: job = self._get_job(job_id) return { "job_id": int(job.job_id), "client": job.client.as_hex, "freelancer": job.freelancer.as_hex, "arbiter": job.arbiter.as_hex, "title": job.title, "description": job.description, "status": int(job.status), "status_label": JOB_STATUS_LABELS.get(int(job.status), "UNKNOWN"), "milestone_count": int(job.milestone_count), "milestones_paid": int(job.milestones_paid), "milestones_refunded": int(job.milestones_refunded), "milestones_cancelled": int(job.milestones_cancelled), "total_deposited": int(job.total_deposited), "total_released": int(job.total_released), "total_refunded": int(job.total_refunded), "platform_fee_bps": int(job.platform_fee_bps), "required_bond": int(job.required_bond), "bond_deposited": int(job.bond_deposited), "bond_settled": job.bond_settled, "deadline": int(job.deadline), "created_at": int(job.created_at), } @gl.public.view def get_milestone(self, job_id: int, milestone_index: int) -> TreeMap[str, typing.Any]: milestone = self._get_milestone(job_id, milestone_index) return { "job_id": int(milestone.job_id), "index": int(milestone.index), "title": milestone.title, "description": milestone.description, "acceptance_criteria": milestone.acceptance_criteria, "amount": int(milestone.amount), "deposited": int(milestone.deposited), "status": int(milestone.status), "status_label": MS_STATUS_LABELS.get(int(milestone.status), "UNKNOWN"), "deliverable_url": milestone.deliverable_url, "revision_count": int(milestone.revision_count), "max_revisions": int(milestone.max_revisions), "last_verdict": milestone.last_verdict, "last_reasoning": milestone.last_reasoning, "disputed_by": milestone.disputed_by.as_hex, "dispute_reason": milestone.dispute_reason, "created_at": int(milestone.created_at), "submitted_at": int(milestone.submitted_at), "resolved_at": int(milestone.resolved_at), "resolved_by_arbiter": milestone.resolved_by_arbiter, } @gl.public.view def get_job_milestones(self, job_id: int) -> DynArray[TreeMap[str, typing.Any]]: job = self._get_job(job_id) results: DynArray[TreeMap[str, typing.Any]] = [] for index in range(int(job.milestone_count)): results.append(self.get_milestone(job_id, index)) return results @gl.public.view def get_reputation(self, address: str) -> TreeMap[str, typing.Any]: addr = Address(address) if addr not in self.reputation: return { "jobs_as_client": 0, "jobs_as_freelancer": 0, "milestones_completed": 0, "milestones_disputed": 0, "milestones_cancelled_or_refunded": 0, "total_earned": 0, "total_paid_out": 0, } rep = self.reputation[addr] return { "jobs_as_client": int(rep.jobs_as_client), "jobs_as_freelancer": int(rep.jobs_as_freelancer), "milestones_completed": int(rep.milestones_completed), "milestones_disputed": int(rep.milestones_disputed), "milestones_cancelled_or_refunded": int(rep.milestones_cancelled_or_refunded), "total_earned": int(rep.total_earned), "total_paid_out": int(rep.total_paid_out), } @gl.public.view def get_job_counter(self) -> int: """Total number of jobs ever created; also the exclusive upper bound for valid job ids (`0 .. get_job_counter() - 1`).""" return int(self.job_counter) @gl.public.view def get_contract_balance(self) -> int: """Native token balance currently held by this contract. In a healthy state this always equals the sum of every live milestone's `deposited` field across every job -- a useful sanity check for anyone auditing the ledger accounting described in the module docstring.""" return int(self.balance) @gl.public.view def get_status_labels(self) -> TreeMap[str, typing.Any]: """Returns the integer-to-label mappings for job and milestone status codes, so a front-end or block explorer never has to hard-code them separately from this contract.""" return { "job_status": {str(k): v for k, v in JOB_STATUS_LABELS.items()}, "milestone_status": {str(k): v for k, v in MS_STATUS_LABELS.items()}, } @gl.public.view def list_jobs(self, start_id: int, limit: int) -> DynArray[TreeMap[str, typing.Any]]: """ Paginated job listing. `limit` is clamped to `MAX_LISTING_SCAN` so a single view call can never be forced to iterate an unbounded range as the protocol accumulates jobs over time. """ if start_id < 0: raise gl.vm.UserError("start_id must not be negative") bounded_limit = min(max(limit, 0), MAX_LISTING_SCAN) results: DynArray[TreeMap[str, typing.Any]] = [] total = int(self.job_counter) end = min(start_id + bounded_limit, total) for job_id in range(start_id, end): key = u256(job_id) if key in self.jobs: results.append(self.get_job(job_id)) return results @gl.public.view def get_disputed_milestones(self, start_id: int, limit: int) -> DynArray[TreeMap[str, typing.Any]]: """ Scans jobs `start_id .. start_id + limit` (bounded by `MAX_LISTING_SCAN`, same pagination discipline as `list_jobs`) and returns every milestone currently in `MS_DISPUTED`, across all of their milestones. Intended for an arbiter-facing dashboard that needs to find work awaiting its attention without needing its own off-chain index of every job/milestone pair. """ if start_id < 0: raise gl.vm.UserError("start_id must not be negative") bounded_limit = min(max(limit, 0), MAX_LISTING_SCAN) results: DynArray[TreeMap[str, typing.Any]] = [] total = int(self.job_counter) end = min(start_id + bounded_limit, total) for job_id in range(start_id, end): key = u256(job_id) if key not in self.jobs: continue job = self.jobs[key] for index in range(int(job.milestone_count)): milestone_key = self._milestone_key(job_id, index) milestone = self.milestones[milestone_key] if int(milestone.status) == MS_DISPUTED: results.append(self.get_milestone(job_id, index)) return results @gl.public.view def get_freelancer_summary(self, address: str) -> TreeMap[str, typing.Any]: """ Convenience aggregate combining an address's on-chain `Reputation` record with a simple derived completion rate, so a front-end doesn't need to compute `milestones_completed / (milestones_completed + milestones_cancelled_or_refunded)` itself from the raw counters. """ rep = self.get_reputation(address) completed = rep["milestones_completed"] failed = rep["milestones_cancelled_or_refunded"] total = completed + failed completion_rate_bps = 0 if total == 0 else (completed * BPS_DENOMINATOR) // total rep["total_scored_milestones"] = total rep["completion_rate_bps"] = completion_rate_bps return rep