Skip to content

docs(ai-explainer): document impl-diff pipeline step#228

Merged
spalen0 merged 1 commit into
mainfrom
docs-impl-diff
May 20, 2026
Merged

docs(ai-explainer): document impl-diff pipeline step#228
spalen0 merged 1 commit into
mainfrom
docs-impl-diff

Conversation

@spalen0
Copy link
Copy Markdown
Collaborator

@spalen0 spalen0 commented May 20, 2026

Docs-only follow-up to #226 and #227. The pipeline gained a structural implementation-diff step that wasn't reflected in `utils/llm/README.md`.

Changes

"Proxy Upgrade Detection" section (now "Proxy Upgrade Detection & Implementation Diff") covers:

  • All three recognized upgrade selectors:
    • `upgradeTo(address)` and `upgradeToAndCall(address,bytes)` — called on the proxy itself
    • `upgradeAndCall(address,address,bytes)` — called on the OZ ProxyAdmin (proxy address comes from the calldata, not the tx target)
  • The `ProxyUpgrade(proxy_address, new_implementation)` dataclass return type, with a note that `proxy_address` may differ from `target` (and the Telegram alert surfaces both).
  • Selector short-circuit before calldata decoding so non-upgrade calls don't pay the Sourcify 4byte timeout.
  • The structural diff via `utils/impl_diff.py`:
    • Functions added / removed / changed visibility or modifiers (overload-aware via name + arg-types).
    • Storage layout safety check, including OZ trailing-gap consumption recognition (`uintN[K] __gap` shrinks by exactly the number of inserted vars).
    • EIP-7201 namespaced storage detection — positional layout check skipped with a note.
    • Default-internal state vars (no visibility modifier) now captured; function locals excluded via brace-depth tracking.

Example assembled prompt updated to show the new `--- Proxy Upgrade ---` block content (Old/New impl labels, function add list, storage-layout verdict).

Module structure lists `utils/impl_diff.py`.

No code changes

Pure README update. CI will be fast.

Expands the README's "Proxy Upgrade Detection" section to cover the new
implementation-diff feature shipped in #226 and #227:

- All three recognized upgrade selectors (incl. OZ ProxyAdmin's
  upgradeAndCall) and the ProxyUpgrade dataclass returned.
- Selector short-circuit before calldata decoding (no Sourcify lookup
  for non-upgrade calls).
- Structural diff between old/new impl: function add/remove/changed
  visibility, storage layout safety with OZ trailing-gap consumption,
  EIP-7201 namespaced storage detection.
- Default-internal state vars now captured (visibility no longer
  required); function locals excluded via brace-depth tracking.

Updates the example assembled prompt to show the new "--- Proxy Upgrade
---" block content (with Old/New impl labels and function/state diff)
and adds utils/impl_diff.py to the module-structure listing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@spalen0 spalen0 merged commit 72e1c9c into main May 20, 2026
2 checks passed
@spalen0 spalen0 deleted the docs-impl-diff branch May 20, 2026 13:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant