Add contract reference table to LLM reports

[spalen0]

Summary

• add a deterministic ## Reference table to full Wavey Gist reports
• include the execution authority, alert contract, call targets, address-valued calldata arguments, nested calldata addresses, and protocol-context addresses
• preserve every role/description pair when one address has multiple uses
• inspect calldata nested in scalar bytes, arrays, and tuples using the existing offline decoder and recursion limit
• reuse existing decoded calls and resolved labels without adding LLM calls, prompt tokens, RPC reads, or external API requests

Inspired by the Reference section in this Wavey Gist.

Example

Address	Label	Role	Description
0x4B174afbeD7b98BA01F50E36109EEE5e6d327c32	Infinifi Shorttimelock	Executor	Executor: Execution authority for the governance transaction
0x11F6FAb3f4D8635880C3e80cbae8AEF8136D4189	RWAEscrowRateManager	Call target	Call target: Receives setRate(address,uint256)
0x6439eb9DADC7977BC1ADC027B10Fb1749AF869A5	New Silver 2 Escrow	Calldata argument; Protocol context	Calldata argument: Passed as escrow to setRate(address,uint256) Protocol context: Resolved by the INFINIFI protocol adapter
0x79e1B8e45932A7C802eA3dAb3844e5DEa68d971f	New Silver 2 Senior	Protocol context	Protocol context: Resolved by the INFINIFI protocol adapter
0xE4C72b4dE5b0F9ACcEA880Ad0b1F944F85A9dAA0	New Silver Series 2 DROP	Protocol context	Protocol context: Resolved by the INFINIFI protocol adapter

LLM cost

None. The table is generated locally after the LLM response from data already collected for the report. The only size increase is the final gist Markdown payload.

Testing

• uv run pytest tests/ — 867 passed, 4 skipped
• uv run ruff check .
• uv run ruff format --check .
• uv run mypy --follow-imports=skip utils/llm/report.py
• uv audit --preview-features audit-command
• uvx prek run

[spalen0]

Resolved the review findings in 39bde19.

Finding	Resolution
Role and description columns could lose their pairing	Store and render each (role, description) usage together; descriptions are explicitly role-prefixed.
Executor wording implied an already-executed transaction	Describe it as the execution authority, which is accurate for pending Safe transactions and scheduled timelock operations.
Nested bytes[] payloads were not inspected	Recursively inspect bytes leaves inside arrays and tuples while preserving the existing nested-calldata recursion limit.
README used report contract instead of the emitted Alert contract role	Aligned the terminology.
README explorer links were truncated and invalid	Replaced them with full checksummed address links.

Added regression tests for multi-role addresses, bytes[] payloads, and tuple-contained calldata.

Validation:

• uv run pytest tests/ — 867 passed, 4 skipped
• uv run ruff check .
• uv run ruff format --check .
• uv run mypy --follow-imports=skip utils/llm/report.py
• uv audit --preview-features audit-command
• uvx prek run