io.github.beepboop2025/lucent

PURPOSE: Authoring-time review of an ERC-7730 Clear Signing descriptor. Combines three lenses — audit (does the wallet screen show the right fields, grade A-F), comprehension (a plain-language consequence sentence + risk tier per function), and danger (structural attack primitives). Returns {verdict: {gate, reason}, audit, comprehension, danger}. GUIDELINES: Use this while writing or reviewing a descriptor. Never use it to approve a pending transaction because it does not bind chain, address, calldata, or value; use preflight_transaction for every pending call. LIMITATIONS: Static full-descriptor analysis with transaction_bound=false. It does NOT simulate the transaction against live chain state, detect economic exploits (price manipulation, MEV), or judge whether the counterparty is honest. It reports authoring defects; its verdict is not a pending-call decision. EXAMPLE: check_descriptor({"descriptor": {"context": {...}, "display": {"formats": {...}}}}) -> {"verdict": {"gate": "block", "reason": "1 CRITICAL danger primitive…"}, …}

PURPOSE: Review UX copy for ONE function of an ERC-7730 descriptor — an unbound actor->action->object consequence sentence ('You let {spender} move up to {amount} of your tokens…'), a risk tier (CRITICAL/HIGH/MEDIUM/LOW), and the specific reason it earned that tier. Returns {found, function, sentence, tier, reason}. GUIDELINES: Use this only while authoring or reviewing confirmation copy. It is not bound to chain, sender, destination, calldata, or value and MUST NOT approve a pending signature. Use preflight_transaction for every pending call. LIMITATIONS: Explains a single function's intent and comprehension risk; it does not run the danger-primitive scan (use check_descriptor / scan_contract for that) and does not simulate on-chain effects. Returns found=false with the available function names if the name is not in the descriptor. EXAMPLE: explain_signature({"descriptor": {…}, "function": "approve"}) -> {"found": true, "tier": "HIGH", "sentence": "You let … spend up to …", "reason": "an ERC-20 allowance lets the spender pull tokens…"}

PURPOSE: Analyze one exact unsigned EVM call before it is presented to a signer. Binds chain_id, sender, destination, calldata selector, decoded arguments, ETH value, and an inline ERC-7730 descriptor into one fingerprinted result. Only the selected function is assessed. Returns present/review/block plus audit, comprehension, danger, assurance, and explicit limitations. GUIDELINES: Use this as the PRIMARY transaction-time gate. block means the screen is missing essential information or the selected ABI function has a CRITICAL known danger pattern. review means a human must inspect the named risk. safe_to_present means only that the call is clear enough to show; it does not mean execution is safe. LIMITATIONS: Caller-supplied descriptor and ABI, static analysis only. No bytecode verification, proxy resolution, runtime simulation, MEV analysis, or counterparty judgment.

PURPOSE: Assess a deployed EVM contract for structural danger primitives by ADDRESS — no descriptor needed. Fetches the contract's verified ABI from Sourcify and flags every signable function that is a 'loaded gun': arbitrary external call, delegatecall, self-destruct, upgrade-and-execute, unbounded delegation (setApprovalForAll), authority transfer, or value sweep. Returns {matched, danger_findings: [{severity, function, primitive, why}], critical, worst_severity}. GUIDELINES: Call this to vet a contract an agent is about to interact with BEFORE any transaction is even built — the earliest possible safety check. Treat any CRITICAL finding as a strong signal not to interact without human review. Once a pending call is built, use preflight_transaction; neither this discovery scan nor check_descriptor is a signing gate. LIMITATIONS: Flags DANGEROUS CAPABILITIES the contract exposes, not proof of malicious intent — many legitimate contracts expose upgrade or admin functions. Requires a verified ABI on Sourcify; returns matched=false with a reason when the ABI is unavailable or the fetch fails. Does not analyze bytecode, proxy implementations beyond the fetched ABI, or runtime behavior. EXAMPLE: scan_contract({"chain_id": 1, "address": "0x00000000006c3852cbEf3e08E8dF289169EdE581"})