# { "Depends": "py-genlayer:1jb45aa8ynh2a9c9xn3b7qqh8sm5q93hwfp7jqmwsfhh8jpz09h6" } # SentryBond — automated, self-adjudicating SLA escrow for decentralized services. # # Designed for trustless verification of uptime service level agreements. # Adjudication uses independent fetching of evidence documents from public # endpoints, followed by natural language consensus over structured outcomes. # Payouts route through EVM value transfer messages to target Externally # Owned Accounts (EOAs). import json from datetime import datetime, timezone from genlayer import * # --- Error Taxonomies --- ERR_INPUT = "[ERR_INPUT]" # Invalid state or parameters (reverts early) ERR_TRANSIENT = "[ERR_TRANSIENT]" # Remote network timeouts / status 5xx (forces validator disagreement) ERR_INVALID = "[ERR_INVALID_DATA]" # Unexpected 4xx status codes (forces validator disagreement) ERR_LLM = "[ERR_LLM_OUTPUT]" # Malformed LLM output (forces validator disagreement) # --- EVM Payout Transfer Stub --- @gl.evm.contract_interface class _EoaTransferGate: class View: pass class Write: pass # --- State Taxonomy --- STATE_AWAITING_DEPOSIT = "STATE_AWAITING_DEPOSIT" STATE_AWAITING_LOCK = "STATE_AWAITING_LOCK" STATE_OPERATIONAL = "STATE_OPERATIONAL" STATE_DISPUTED = "STATE_DISPUTED" STATE_DECIDED = "STATE_DECIDED" STATE_SETTLED = "STATE_SETTLED" # --- Payout Resolution Modes --- MODE_NONE = "" MODE_CUSTOMER_RELEASE = "MODE_CUSTOMER_RELEASE" MODE_VALIDATOR_DECISION = "MODE_VALIDATOR_DECISION" MODE_MUTUAL_RELEASE = "MODE_MUTUAL_RELEASE" MODE_DEADLOCK_FALLBACK = "MODE_DEADLOCK_FALLBACK" MODE_DEPOSIT_RECLAIM = "MODE_DEPOSIT_RECLAIM" # --- Adjudication Outcomes --- OUTCOME_SLA_COMPLIANT = "SLA_COMPLIANT" OUTCOME_MODERATE_BREACH = "MODERATE_BREACH" OUTCOME_SEVERE_BREACH = "SEVERE_BREACH" OUTCOME_UNVERIFIABLE_INCIDENT = "UNVERIFIABLE_INCIDENT" # Outcome refund bps map (1/10000) _OUTCOME_REFUND_BPS = { OUTCOME_SLA_COMPLIANT: 0, OUTCOME_MODERATE_BREACH: 3500, OUTCOME_SEVERE_BREACH: 10000, OUTCOME_UNVERIFIABLE_INCIDENT: 0, } _SETTLEABLE_OUTCOMES = (OUTCOME_SLA_COMPLIANT, OUTCOME_MODERATE_BREACH, OUTCOME_SEVERE_BREACH) _BPS_DENOM = 10000 _DEADLOCK_MIN_SECONDS = 3600 _DEADLOCK_MAX_SECONDS = 2592000 _TRANSIENT_STATUS = (408, 425, 429) _MISSING_STATUS = (404, 410) _INACCESSIBLE_STATUS = (401, 403) _ZERO_ADDRESS = Address(bytes(20)) def _now() -> int: """Deterministic time oracle based on consensus transaction timestamp.""" return int(datetime.now(timezone.utc).timestamp()) class SentryBond(gl.Contract): customer_address: Address provider_address: Address # authoritative URLs pinned at deployment sla_spec_url: str uptime_feed_url: str status_log_url: str maintenance_feed_url: str escrow_amount: u256 status: str resolution_mode: str # dispute parameters incident_window: str dispute_opened_at: u256 outcome: str refund_bps: u256 maintenance_qualified: bool violated_clause_ids: DynArray[str] ruling_reason: str unverifiable_ruled_at: u256 # mutual split settlement variables settlement_pending: bool settlement_proposer: Address settlement_refund_bps: u256 # deadlock timers configurations deadlock_refund_bps: u256 dispute_deadlock_seconds: u256 unverifiable_deadlock_seconds: u256 def __init__( self, provider: Address, sla_spec_url: str, uptime_feed_url: str, status_log_url: str, maintenance_feed_url: str, deadlock_refund_bps: int, dispute_deadlock_seconds: int, unverifiable_deadlock_seconds: int, ): """Initialize customer escrow, pin monitoring feeds, and define safety bounds.""" actual_provider = provider if not isinstance(actual_provider, Address): if isinstance(actual_provider, int): actual_provider = Address(actual_provider.to_bytes(20, byteorder="big")) elif isinstance(actual_provider, str): hex_str = actual_provider.strip() if hex_str.startswith("0x"): hex_str = hex_str[2:] actual_provider = Address(bytes.fromhex(hex_str)) elif isinstance(actual_provider, bytes): actual_provider = Address(actual_provider) else: raise gl.vm.UserError(f"{ERR_INPUT} Provider must be an Address, int, or hex string") if actual_provider == _ZERO_ADDRESS: raise gl.vm.UserError(f"{ERR_INPUT} Provider cannot be zero address") if actual_provider == gl.message.sender_address: raise gl.vm.UserError(f"{ERR_INPUT} Customer and provider must be different") if not sla_spec_url or not uptime_feed_url: raise gl.vm.UserError(f"{ERR_INPUT} Authoritative SLA and monitor feed required") if deadlock_refund_bps < 0 or deadlock_refund_bps > _BPS_DENOM: raise gl.vm.UserError(f"{ERR_INPUT} Deadlock split out of range") if dispute_deadlock_seconds < _DEADLOCK_MIN_SECONDS or dispute_deadlock_seconds > _DEADLOCK_MAX_SECONDS: raise gl.vm.UserError(f"{ERR_INPUT} Dispute deadlock limit violated") if unverifiable_deadlock_seconds < _DEADLOCK_MIN_SECONDS or unverifiable_deadlock_seconds > _DEADLOCK_MAX_SECONDS: raise gl.vm.UserError(f"{ERR_INPUT} Unverifiable deadlock limit violated") self.customer_address = gl.message.sender_address self.provider_address = actual_provider self.sla_spec_url = sla_spec_url self.uptime_feed_url = uptime_feed_url self.status_log_url = status_log_url self.maintenance_feed_url = maintenance_feed_url self.escrow_amount = 0 self.status = STATE_AWAITING_DEPOSIT self.resolution_mode = MODE_NONE self.incident_window = "" self.dispute_opened_at = 0 self.outcome = "" self.refund_bps = 0 self.maintenance_qualified = False self.ruling_reason = "" self.unverifiable_ruled_at = 0 self.settlement_pending = False self.settlement_proposer = _ZERO_ADDRESS self.settlement_refund_bps = 0 self.deadlock_refund_bps = deadlock_refund_bps self.dispute_deadlock_seconds = dispute_deadlock_seconds self.unverifiable_deadlock_seconds = unverifiable_deadlock_seconds # ================================ Deposit Escrow ================================ @gl.public.write.payable def deposit_escrow(self) -> None: """Lock native funds from the customer in escrow.""" if gl.message.sender_address != self.customer_address: raise gl.vm.UserError(f"{ERR_INPUT} Only the customer may deposit escrow") if self.status != STATE_AWAITING_DEPOSIT: raise gl.vm.UserError(f"{ERR_INPUT} Deposit already completed") value = gl.message.value if value == 0: raise gl.vm.UserError(f"{ERR_INPUT} Escrow value must exceed zero") self.escrow_amount = value self.status = STATE_AWAITING_LOCK # ========================== Reclaim Before Lock ========================== @gl.public.write def reclaim_before_lock(self) -> None: """Allow customer to reclaim escrow if the provider hasn't locked the agreement yet.""" if gl.message.sender_address != self.customer_address: raise gl.vm.UserError(f"{ERR_INPUT} Only the customer may reclaim") if self.status != STATE_AWAITING_LOCK: raise gl.vm.UserError(f"{ERR_INPUT} Escrow cannot be reclaimed in this state") self.outcome = OUTCOME_SEVERE_BREACH self._settle(_BPS_DENOM, MODE_DEPOSIT_RECLAIM) # ============================ Lock Agreement ============================ @gl.public.write def lock_agreement(self) -> None: """Provider signs and locks the agreement, committing to the SLA parameters.""" if gl.message.sender_address != self.provider_address: raise gl.vm.UserError(f"{ERR_INPUT} Only the provider may lock the agreement") if self.status != STATE_AWAITING_LOCK: raise gl.vm.UserError(f"{ERR_INPUT} Agreement not ready for locking") self.status = STATE_OPERATIONAL # ========================== Settle Escrow ========================== @gl.public.write def settle_escrow(self) -> None: """Settle native funds per the finalized dispute evaluation. Single-shot and idempotent.""" sender = gl.message.sender_address if sender != self.customer_address and sender != self.provider_address: raise gl.vm.UserError(f"{ERR_INPUT} Unauthorized caller") if self.status != STATE_DECIDED: raise gl.vm.UserError(f"{ERR_INPUT} No active decision to settle") if self.outcome not in _SETTLEABLE_OUTCOMES: raise gl.vm.UserError(f"{ERR_INPUT} Outcome {self.outcome} is not settleable") self._settle(int(self.refund_bps), MODE_VALIDATOR_DECISION) def _settle(self, refund_bps: int, mode: str) -> None: """Deduct and route native funds to customer/provider via EVM EoaTransferGate stubs.""" total = self.escrow_amount customer_share = total * refund_bps // _BPS_DENOM provider_share = total - customer_share self.refund_bps = refund_bps self.resolution_mode = mode self.settlement_pending = False # Set status to settled before transferring to prevent re-entrant payouts self.status = STATE_SETTLED if customer_share > 0: _EoaTransferGate(self.customer_address).emit_transfer(value=u256(customer_share)) if provider_share > 0: _EoaTransferGate(self.provider_address).emit_transfer(value=u256(provider_share)) # ========================== Waive Dispute ========================== @gl.public.write def waive_dispute(self) -> None: """Allow customer to waive any dispute and release 100% of escrow to the provider.""" if gl.message.sender_address != self.customer_address: raise gl.vm.UserError(f"{ERR_INPUT} Only the customer may waive dispute") if self.status != STATE_OPERATIONAL: raise gl.vm.UserError(f"{ERR_INPUT} Service agreement is not operational") self.outcome = OUTCOME_SLA_COMPLIANT self._settle(0, MODE_CUSTOMER_RELEASE) # ========================== File Dispute ========================== @gl.public.write def file_dispute(self, incident_window: str) -> None: """File a formal SLA dispute specifying the incident time window.""" sender = gl.message.sender_address if sender != self.customer_address and sender != self.provider_address: raise gl.vm.UserError(f"{ERR_INPUT} Unauthorized caller") if self.status != STATE_OPERATIONAL: raise gl.vm.UserError(f"{ERR_INPUT} Service agreement not operational") if not incident_window: raise gl.vm.UserError(f"{ERR_INPUT} Dispute incident window required") # Clear historical dispute variables self.outcome = "" self.refund_bps = 0 self.maintenance_qualified = False self.violated_clause_ids.clear() self.ruling_reason = "" self.unverifiable_ruled_at = 0 self.settlement_pending = False self.settlement_proposer = _ZERO_ADDRESS self.settlement_refund_bps = 0 self.incident_window = incident_window self.dispute_opened_at = _now() self.status = STATE_DISPUTED # ========================== Evaluate Dispute ========================== @gl.public.write def evaluate_dispute(self) -> None: """Query validator consensus to adjudicate the SLA dispute based on public evidence.""" sender = gl.message.sender_address if sender != self.customer_address and sender != self.provider_address: raise gl.vm.UserError(f"{ERR_INPUT} Unauthorized caller") if self.status != STATE_DISPUTED: raise gl.vm.UserError(f"{ERR_INPUT} No active dispute to evaluate") sla_url = self.sla_spec_url monitor_url = self.uptime_feed_url status_url = self.status_log_url maint_url = self.maintenance_feed_url window = self.incident_window def leader_fn() -> dict: return _adjudicate(sla_url, monitor_url, status_url, maint_url, window) def validator_fn(leader_res: gl.vm.Result) -> bool: if not isinstance(leader_res, gl.vm.Return): return False try: mine = _adjudicate(sla_url, monitor_url, status_url, maint_url, window) except Exception: return False return _decisions_match(leader_res.calldata, mine) result = gl.vm.run_nondet_unsafe(leader_fn, validator_fn) self.outcome = result["outcome"] self.refund_bps = int(result["refund_bps"]) self.maintenance_qualified = bool(result["maintenance_qualified"]) self.violated_clause_ids.clear() for cid in result["violated_clause_ids"]: self.violated_clause_ids.append(str(cid)) self.ruling_reason = str(result.get("reasoning", ""))[:2000] self.status = STATE_DECIDED if self.outcome == OUTCOME_UNVERIFIABLE_INCIDENT: self.unverifiable_ruled_at = _now() # ======================= Mutual Negotiated Release ======================= @gl.public.write def propose_split(self, refund_bps: int) -> None: """Propose a mutual split of the escrow if the outcome is UNVERIFIABLE_INCIDENT.""" sender = gl.message.sender_address if sender != self.customer_address and sender != self.provider_address: raise gl.vm.UserError(f"{ERR_INPUT} Unauthorized caller") if self.status != STATE_DECIDED or self.outcome != OUTCOME_UNVERIFIABLE_INCIDENT: raise gl.vm.UserError(f"{ERR_INPUT} Mutual split not available in this state") if refund_bps < 0 or refund_bps > _BPS_DENOM: raise gl.vm.UserError(f"{ERR_INPUT} Refund split basis points out of range") self.settlement_pending = True self.settlement_proposer = sender self.settlement_refund_bps = refund_bps @gl.public.write def accept_split(self) -> None: """Accept the proposed split from the counterparty, completing the settlement.""" sender = gl.message.sender_address if sender != self.customer_address and sender != self.provider_address: raise gl.vm.UserError(f"{ERR_INPUT} Unauthorized caller") if self.status != STATE_DECIDED or self.outcome != OUTCOME_UNVERIFIABLE_INCIDENT: raise gl.vm.UserError(f"{ERR_INPUT} Mutual split not available in this state") if not self.settlement_pending: raise gl.vm.UserError(f"{ERR_INPUT} No active split proposal to accept") if sender == self.settlement_proposer: raise gl.vm.UserError(f"{ERR_INPUT} Cannot accept your own split proposal") self._settle(int(self.settlement_refund_bps), MODE_MUTUAL_RELEASE) # ========================== Deadlock Fallbacks ========================== @gl.public.write def unwind_deadlock(self) -> None: """Free locked funds deterministically if dispute or unverifiable timeouts expire.""" sender = gl.message.sender_address if sender != self.customer_address and sender != self.provider_address: raise gl.vm.UserError(f"{ERR_INPUT} Unauthorized caller") now = _now() if self.status == STATE_DISPUTED: deadline = int(self.dispute_opened_at) + int(self.dispute_deadlock_seconds) if now < deadline: raise gl.vm.UserError(f"{ERR_INPUT} Dispute deadlock period still active") elif self.status == STATE_DECIDED and self.outcome == OUTCOME_UNVERIFIABLE_INCIDENT: deadline = int(self.unverifiable_ruled_at) + int(self.unverifiable_deadlock_seconds) if now < deadline: raise gl.vm.UserError(f"{ERR_INPUT} Unverifiable deadlock period still active") else: raise gl.vm.UserError(f"{ERR_INPUT} No active deadlock condition to resolve") self._settle(int(self.deadlock_refund_bps), MODE_DEADLOCK_FALLBACK) # ================================== Views ================================== @gl.public.view def get_state(self) -> dict: return { "customer": self.customer_address.as_hex, "provider": self.provider_address.as_hex, "status": self.status, "resolution_mode": self.resolution_mode, "escrow_amount": self.escrow_amount, "incident_window": self.incident_window, "dispute_opened_at": self.dispute_opened_at, "outcome": self.outcome, "refund_bps": self.refund_bps, "maintenance_qualified": self.maintenance_qualified, "violated_clause_ids": [c for c in self.violated_clause_ids], "ruling_reason": self.ruling_reason, "unverifiable_ruled_at": self.unverifiable_ruled_at, "settlement_pending": self.settlement_pending, "settlement_proposer": self.settlement_proposer.as_hex, "settlement_refund_bps": self.settlement_refund_bps, } @gl.public.view def get_settlement_status(self) -> dict: """Verify value movement off the live wasi native balance.""" balance = int(gl.get_contract_at(gl.message.contract_address).balance) settled = self.status == STATE_SETTLED customer_share = self.escrow_amount * self.refund_bps // _BPS_DENOM return { "status": self.status, "settlement_queued": settled, "payout_complete": settled and balance == 0, "contract_balance_atto": u256(balance), "escrow_amount": self.escrow_amount, "expected_customer_atto": u256(customer_share) if settled else u256(0), "expected_provider_atto": ( u256(self.escrow_amount - customer_share) if settled else u256(0) ), } @gl.public.view def get_evidence_sources(self) -> dict: return { "sla_spec_url": self.sla_spec_url, "uptime_feed_url": self.uptime_feed_url, "status_log_url": self.status_log_url, "maintenance_feed_url": self.maintenance_feed_url, } @gl.public.view def get_deadlock_config(self) -> dict: return { "deadlock_refund_bps": self.deadlock_refund_bps, "dispute_deadlock_seconds": self.dispute_deadlock_seconds, "unverifiable_deadlock_seconds": self.unverifiable_deadlock_seconds, } @gl.public.view def get_deadlock_status(self) -> dict: now = _now() applicable_deadline = 0 available = False if self.status == STATE_DISPUTED: applicable_deadline = int(self.dispute_opened_at) + int(self.dispute_deadlock_seconds) available = now >= applicable_deadline elif self.status == STATE_DECIDED and self.outcome == OUTCOME_UNVERIFIABLE_INCIDENT: applicable_deadline = int(self.unverifiable_ruled_at) + int( self.unverifiable_deadlock_seconds ) available = now >= applicable_deadline return { "status": self.status, "now": now, "dispute_opened_at": self.dispute_opened_at, "unverifiable_ruled_at": self.unverifiable_ruled_at, "applicable_deadline": applicable_deadline, "unwind_deadlock_available": available, "deadlock_refund_bps": self.deadlock_refund_bps, } # ============================ Adjudication Helpers ============================ def _fetch(url: str) -> tuple: """Fetch URL contents with status code handling and exception categorisation.""" try: res = gl.nondet.web.get(url) except gl.vm.UserError: raise except Exception: raise gl.vm.UserError(f"{ERR_TRANSIENT} Network connection timeout") st = res.status if st in _TRANSIENT_STATUS or st >= 500: raise gl.vm.UserError(f"{ERR_TRANSIENT} Host returned status {st}") if st in _MISSING_STATUS: return ("MISSING", "[EVIDENCE REMOVED OR NOT FOUND]") if st in _INACCESSIBLE_STATUS: return ("INACCESSIBLE", "[EVIDENCE RESTRICTED OR NO AUTH]") if 400 <= st < 500: raise gl.vm.UserError(f"{ERR_INVALID} Host rejected with status {st}") body = res.body or b"" return ("AVAILABLE", body.decode("utf-8", errors="replace")[:8000]) def _normalize_clause_ids(raw: object) -> list: if raw is None: return [] if not isinstance(raw, (list, tuple)): raise gl.vm.UserError(f"{ERR_LLM} violated_clause_ids must be a array") seen = set() out = [] for item in raw: cid = str(item).strip() if cid and cid not in seen: seen.add(cid) out.append(cid) out.sort() return out def _coerce_bool(raw: object) -> bool: if isinstance(raw, bool): return raw if isinstance(raw, str): return raw.strip().lower() in ("true", "yes", "1") if isinstance(raw, int): return raw != 0 return False def _parse_json(text: str) -> dict: first = text.find("{") last = text.rfind("}") if first == -1 or last == -1: raise gl.vm.UserError(f"{ERR_LLM} Invalid JSON formatting") return json.loads(text[first : last + 1]) def _normalize(raw: object) -> dict: data = raw if isinstance(data, str): data = _parse_json(data) if not isinstance(data, dict): raise gl.vm.UserError(f"{ERR_LLM} Decoded output type is not a dictionary") outcome = str(data.get("outcome", "")).strip().upper() if outcome not in _OUTCOME_REFUND_BPS: raise gl.vm.UserError(f"{ERR_LLM} Unknown dispute outcome: {data.get('outcome')}") maintenance_qualified = _coerce_bool(data.get("maintenance_qualified")) refund_bps = _OUTCOME_REFUND_BPS[outcome] if outcome in (OUTCOME_MODERATE_BREACH, OUTCOME_SEVERE_BREACH): violated = _normalize_clause_ids(data.get("violated_clause_ids")) else: violated = [] return { "outcome": outcome, "refund_bps": refund_bps, "maintenance_qualified": maintenance_qualified, "violated_clause_ids": violated, "reasoning": str(data.get("reasoning", "")), } def _decisions_match(leader: dict, mine: dict) -> bool: return ( leader["outcome"] == mine["outcome"] and int(leader["refund_bps"]) == int(mine["refund_bps"]) and bool(leader["maintenance_qualified"]) == bool(mine["maintenance_qualified"]) and [str(c) for c in leader["violated_clause_ids"]] == [str(c) for c in mine["violated_clause_ids"]] ) def _adjudicate( sla_url: str, monitor_url: str, status_url: str, maint_url: str, incident_window: str, ) -> dict: """Fetch external monitor data and evaluate against SLA definitions inside LLM prompt.""" sla_state, sla_doc = _fetch(sla_url) monitor_state, monitor_doc = _fetch(monitor_url) status_state, status_doc = _fetch(status_url) maint_state, maint_doc = _fetch(maint_url) prompt = """You are an objective auditor resolving an uptime SLA dispute. Evaluate the evidence provided below and output a structured decision. If the authoritative SLA terms or the monitor data is unavailable/restricted, or if you cannot logically make a ruling, you must return UNVERIFIABLE_INCIDENT. DISPUTED INCIDENT WINDOW: {incident_window} SLA AGREEMENT SPECIFICATION [{sla_state}]: {sla_doc} PRIMARY INDEPENDENT MONITOR LOGS [{monitor_state}]: {monitor_doc} SECONDARY PROVIDER STATUS LOGS [{status_state}]: {status_doc} MAINTENANCE SCHEDULES [{maint_state}]: {maint_doc} Evaluation Rules: 1. Verify if downtime occurred inside the incident window according to the primary monitor. 2. Check if the downtime is excused by a maintenance window announced within the SLA-required notice window. If yes, set maintenance_qualified=true, and the downtime does not count as a breach. 3. Classify into one of these outcomes: SLA_COMPLIANT - SLA obligations met, or downtime fully covered by qualified maintenance. MODERATE_BREACH - SLA was violated, but lands within moderate-penalty thresholds. SEVERE_BREACH - SLA was critically violated, warranting a full refund. UNVERIFIABLE_INCIDENT - Evidence is missing or contradictory, preventing a sound decision. Provide ONLY the JSON response without code fences or extra text: {{ "outcome": "SLA_COMPLIANT | MODERATE_BREACH | SEVERE_BREACH | UNVERIFIABLE_INCIDENT", "maintenance_qualified": true | false, "violated_clause_ids": ["", ""], "reasoning": "" }}""".format( incident_window=incident_window, sla_state=sla_state, sla_doc=sla_doc, monitor_state=monitor_state, monitor_doc=monitor_doc, status_state=status_state, status_doc=status_doc, maint_state=maint_state, maint_doc=maint_doc ) raw = gl.nondet.exec_prompt(prompt, response_format="json") return _normalize(raw)