Lucent

Tooling to author, verify, and attest ERC-7730 Clear Signing descriptors for the public registry that compatible wallets read from.

A descriptor is a JSON file that tells a wallet how to render a contract call in plain language, so users see what they are signing instead of raw hex. Lucent covers the full path: find contracts that lack a descriptor, write and harden one, check it beyond schema validity, prove it against real transactions, and produce an ERC-8176 attestation.

For signing agents: the MCP server

An AI agent about to sign a transaction faces exactly the question Lucent's checks answer — is this call safe, and does the screen a human would see actually describe what it does? scripts/mcp_server.py exposes that as an MCP server (stdlib JSON-RPC over stdio) so an agent can pre-flight a signature:

• check_descriptor — one combined gate over an ERC-7730 descriptor: the audit grade (screen shows the right fields), the comprehension grade (a plain-language consequence sentence + risk tier per function), and the danger scan (structural primitives a clear screen can't make safe). Returns a verdict.gate of safe_to_present / review / block to branch on — a CRITICAL danger primitive blocks regardless of how benign the sentence reads.

• explain_signature — the actor→action→object sentence + risk tier + reason for one function, to render a human confirmation before a signature.

• scan_contract — danger-scan a deployed contract by address (fetches the verified ABI from Sourcify), so an agent can assess a contract before any transaction is built.

make mcp    # or: .venv/bin/python scripts/mcp_server.py

Register it as a stdio MCP server pointing at scripts/mcp_server.py from the repo root (see mcp.json). Same transport shape as the sibling Groundcheck and Seiche servers.

Related MCP server: io.github.yugantm/hvtracker-mcp

Install

make setup     # creates .venv and installs requirements (Python 3.12+)

Most stages that read on-chain data need a free Etherscan API key:

export ETHERSCAN_API_KEY=...

Pipeline

A common.py module holds the shared Sourcify and Etherscan clients and ABI utilities.

Audit

erc7730 lint checks that a descriptor is well-formed. audit.py checks whether the on-device screen would mislead a user, which lint does not:

• CRITICAL: a payable function that never shows @.value, or a tokenAmount with no known token.

• HIGH: a signable function with no intent or no visible field, or an address shown as raw hex.

• MEDIUM/LOW: labels or intents past the device character limits, missing interpolated summaries.

It reports a letter grade. to_submission.py refuses to package below grade B. A raw generated draft of the ENS controller scores F; the hardened descriptors score A.

Comprehension risk

Lint checks that a descriptor is well-formed; audit.py checks that the screen shows the right fields. Neither asks the question that "What I Sign Is Not What I See" shows is the real failure: users mis-understand a technically-correct screen. Its studies found people fixate on the amount and recipient and miss scope, delegation, and unlimited allowances — and that a bare field list, even a complete one, leaves comprehension at chance on the dangerous cases. Its Signature Semantic Decoder cut false approvals on unlimited-allowance and phishing transactions by 73% and 46% by rendering an actor→action→object sentence and a risk tier with a reason.

comprehend.py brings that to the descriptor. For each signable function it emits:

• a consequence sentence — who acts on what, plus conditions, built from the ABI and the descriptor's own labels so it renders what the wallet will show: "You let {Operator} transfer ANY of your tokens in this contract, at any time, until you revoke it."

• a risk tier with the clause that earned it — the paper's users rejected bare labels and demanded the why. Patterns scored are the ones the study found people miss: operator grants (setApprovalForAll), ERC-20 allowances (flagged distinctly from ERC-721 token-id approvals, since approve(address,uint256) reads identically but means different things), permits (off-chain, invisible in history), admin/upgrade authority, and raw-hex recipients (the address-poisoning surface).

An unrecognised function with no on-screen intent is reported as an unexplained screen (a caution), never silently cleared — an unexplained screen invites blind approval, which is the failure the paper measures. Run it with make comprehend DESC=…; NameWrapper's setApprovalForAll and the controller's transferOwnership both surface as CRITICAL comprehension risks that lint and audit pass.

Danger surface

Audit asks whether the screen shows the right fields; comprehend asks whether the human understands them. danger.py asks the third question: can this function, by construction, do something a clear screen still can't make safe? A descriptor can render a perfectly honest sentence for execute(address target, bytes data) — "Call {target} with {data}" — and that call can still drain the wallet, because the primitive itself is unbounded.

Runtime systems catch this by instrumenting transaction-trace properties (arXiv:2408.14621: arbitrary CALL/DELEGATECALL/SELFDESTRUCT in the trace). danger.py lifts the same property set to static ABI analysis, so the danger is named before anyone signs:

• CRITICAL — arbitrary external call (a call-family name, or a target-address

  • calldata-blob signature), delegatecall (foreign code in this contract's context), self-destruct, and upgrade-and-execute.

• HIGH — unbounded delegation (setApprovalForAll), authority transfer (ownership / admin / role).

• MEDIUM — value sweep to a caller-supplied address.

Precision is the whole game: a danger scan that cries wolf on safeTransferFrom is worse than none. The detector distinguishes calldata from data-as-content by parameter name (target+data, not any address-plus-bytes), excludes to (a recipient, not a callee), and whitelists the standard ERC receiver hooks — so the shipped ENS bundle raises zero false arbitrary-call flags while a real execute(target,data) drainer is still caught. --strict exits non-zero on any CRITICAL.

Semantic verification

Lint proves a descriptor is well-formed, not that its summary is honest. A descriptor can pass every schema check and still render a benign screen for a call that sends assets elsewhere.

For each test vector, semverify.py fetches the mined receipt (the record of what actually moved), extracts the asset movements and approvals (ETH, ERC-20, ERC-1155, ApprovalForAll), and checks the screen against them: every real recipient and operator is shown, ETH spent is shown, and the field labelled as the recipient matches the address that received the asset.

Worked example, a safeTransferFrom descriptor with the To and From labels swapped:

The receipt is exact for mined transactions. The recipient check is heuristic on field labels; it catches recipient hiding and label spoofing, not every possible mismatch.

Unmined calls — fork replay. A brand-new descriptor for a call that has never been mined (a fresh contract, a rarely-used function) has no receipt to check against. forkreplay.py closes that gap: given a call spec {signer, function, args, value} it forks mainnet at HEAD into a local anvil, impersonates the signer, executes the call against real on-chain state, and reads back the standard eth receipt. That (tx, receipt) pair is handed to semverify.verify_one unchanged — so a label swap or hidden recipient on an unmined call is caught by the identical, tested code path, not a second implementation. Run it with make semverify DESC=… SIMULATE=1 on a test file whose vectors carry a call object instead of a txHash. It needs anvil + cast (foundryup) and an RPC URL (ETH_RPC_URL); without them the call vector is skipped with a reason, never silently passed.

Reviewing a registry PR

The clear-signing governance model asks security reviewers to check descriptor PRs "for correctness, clarity, and adversarial edge cases, then publish your findings clearly." review.py is that role as one command: it composes lint, the screen audit, the comprehension grade, the danger scan, and (when test vectors and an ETHERSCAN_API_KEY are available) semantic verification into a single markdown report ready to post on the pull request:

make review DESC=path/to/calldata-Contract.json OUT=review.md

The overall verdict is the same gate the MCP server exposes to signing agents (safe_to_present / review / block), so a human review and an agent pre-flight can never disagree. Checks that cannot run are reported as explicit skips with the reason, never silently passed. To review a descriptor from a registry PR, fetch its ABI first (make fetch CHAIN=<id> ADDR=<address>) so the audit runs against the verified on-chain ABI.

Post-quantum co-signing

A descriptor hash is keccak256, which is quantum-safe. The ECDSA signature over it is not, and attestations are long-lived. attest.py --pq adds a post-quantum signature over the same hash so the attestation stays verifiable if the signature scheme is broken. The hash is unchanged; only the signature scheme is added.

The signature binds the exact descriptor hash. Keys are read from LUCENT_PQ_* env vars or a gitignored .attester-keys/ directory, written owner-only. No cryptographically-relevant quantum computer exists yet and there is no standard for post-quantum attestations, so this is forward positioning, not a current requirement.

Current state

Three ENS descriptors, each grade A and lint clean against the on-chain ABI, packaged under dist/registry-pr/ens/:

Test vectors are real historical transactions, built with fetch_tx.py <chain> <address> <descriptor>.

A registry PR should be submitted by or on behalf of the contract's owner. The remaining step for the ENS descriptors is that authorization, not code.

Attester registration

attest.py --profile writes an auditor profile (auditors/eip155-1-<address>/profile.json) for a registry PR. Signing an EAS offchain attestation needs the ERC-8176 schema UID (published on clearsigning.org) and an attester key. Without them, attest.py writes an unsigned evidence bundle so the pipeline can run end to end first.