Facet Function Explainer

WHAT IT DOES

Facet Function Explainer is a read-only tool that analyzes specific functions in diamond pattern contracts (EIP-2535), generating AI-powered plain-language explanations of what each function does, which facet implements it, who can call it, and the risks of using it. It reads diamond proxy contract address, facet address, function signature, function selector, facet mapping, implementation bytecode, contract cut events, upgrade history, diamond ownership, privileged function signatures, function visibility, access controls, storage layout, event logs, and transaction history. The tool then presents this data alongside an AI-generated explanation of the function's purpose, implementation facet, access controls, and risks — helping you understand the function's behavior and trustworthiness before interacting with it.

HOW TO USE

Connect your wallet using the BGWallet bridge and select your target network. Enter the diamond proxy contract address and the function signature you want to analyze (e.g., "transfer(address,uint256)"). Click "Analyze facet function" to read on-chain contract data. The tool displays the diamond address, function signature, facet address, function selector, access control type, and function risk level (Low/Medium/High). Detailed information includes visibility, storage layout, upgrade history, privileged functions, owner, and bytecode hash. A usage guidance box provides specific recommendations. An AI explanation appears below the on-chain data, explaining what the specific function does, which facet implements it, who can call it, and the risks of using it before you interact with the function. The wallet's own signature step still protects you — this explanation is informational only and does not replace reviewing what you approve in your wallet.

TECHNICAL MECHANISM

The tool uses ethers.js v5.7.2 with the provider from the BGWallet bridge to read on-chain contract data. No hardcoded contract addresses are used — you are always in control of which contract you trust. When analyzing a facet function, the tool reads the diamond proxy contract address from the user input, reads the facet address by resolving the function selector via the diamond's facet loupe functions (e.g., facetAddress()), reads the function signature from the user input, reads the function selector by hashing the function signature, reads the facet mapping by analyzing the diamond's storage, reads the implementation bytecode via provider.getCode(facet), reads contract cut events via event logs (e.g., DiamondCut), reads upgrade history by scanning event logs, reads diamond ownership via the diamond's owner() function or storage slot, reads privileged function signatures by analyzing function selectors, reads function visibility by analyzing the ABI or bytecode, reads access controls by analyzing function modifiers, reads storage layout by analyzing the bytecode and storage slots, reads event logs by scanning for function-related events, and reads transaction history via provider.getTransactionCount(diamond). The tool fetches event logs by walking backwards in chunks and halving chunk size on failure, ensuring logs are properly read despite varying RPC limitations. The data is formatted and passed to the AI bridge via BGAI.generate() with a structured prompt that includes all the on-chain data read. The AI is instructed to explain what the specific function does, which facet implements it, who can call it, and the risks of using it — while stating plainly that it cannot detect if the facet function's implementation matches its intended behavior beyond bytecode analysis, cannot detect off-chain logic or social engineering attacks, and cannot guarantee that the facet function will remain available if the facet is removed or replaced in a future upgrade. The AI response is capped at 1,024 tokens to ensure concise, focused facet function assessments. All computed values are guarded against negative numbers — if a selector or block number appears invalid, the tool flags it rather than displaying nonsensical values.

WHAT IT CANNOT SEE

This tool cannot detect if the facet function's implementation matches its intended behavior beyond bytecode analysis. It cannot detect off-chain logic or social engineering attacks. It cannot guarantee that the facet function will remain available if the facet is removed or replaced in a future upgrade. It cannot detect malicious intent in the implementation code beyond what is visible in the bytecode. The AI explanation is generated from on-chain data only and cannot detect off-chain function behavior, hidden implementation details, or social engineering attacks. It cannot predict whether a function will be removed or replaced in a future upgrade. The tool does not continuously monitor facet functions; each analysis is a snapshot at the time of the lookup. It cannot detect delayed upgrades, hidden facets, or off-chain factors. The tool does not store any data persistently; all state is in-memory and resets on reload. The AI explanation is informational and does not constitute financial advice, legal advice, or a guarantee of function safety or correctness.

PLEASE NOTE

Facet Function Explainer works exclusively with EVM-compatible chains. It requires a Web3 wallet (MetaMask or similar) and the BGWallet bridge. Explanations are AI-generated from data the app reads on-chain — always review what you are actually signing in your wallet before approving it. Diamond pattern functions carry significant risk including privileged access, storage collisions, and hidden implementation details. Use this tool as a guide only; always cross-check with independent sources and contract audits for critical decisions. This is experimental software; use at your own risk.