Module Permission Explainer

WHAT IT DOES

Module Permission Explainer is a read-only tool that analyzes module permissions in modular contracts, generating AI-powered plain-language explanations of what permissions a module has, who granted them, what functions the module can call, and the risks of those permissions. It reads contract address, module address, module registration status, access control lists, role-based permissions, function signatures, module permissions mapping, governance proposals, upgrade history, owner address, privileged function signatures, event logs, transaction history, and module activation and deactivation status. The tool then presents this data alongside an AI-generated analysis of the module's permissions, identifying potential risks such as privilege escalation, fund access, and governance bypass — helping you understand the trustworthiness of a module before interacting with it.

HOW TO USE

Connect your wallet using the BGWallet bridge and select your target network. Enter the contract address (the module container) and the module address you want to analyze. Click "Analyze module permissions" to read on-chain contract data. The tool displays the contract address, module address, registration status, permissioned functions, and module risk level (Low/Medium/High). Detailed information includes granted by, owner, access control type, role-based permissions, function signatures, activation status, upgrade history, privileged functions, and governance proposals. A risk assessment box provides a summary risk evaluation. An AI explanation appears below the on-chain data, explaining what permissions the module has, who granted them, what functions the module can call, and the risks of those permissions before you interact with the module or its functions. 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 module permissions, the tool reads the contract address from the user input, reads the module address from the user input, checks module registration status via the contract's module registry (e.g., isModuleRegistered()), reads access control lists via the contract's access control functions (e.g., getRoleMembers()), reads role-based permissions via the contract's role management functions, reads function signatures from the module's ABI or bytecode, reads module permissions mapping via the contract's permission storage, reads governance proposals via the governance contract (if available), reads upgrade history by scanning event logs (e.g., ModuleAdded, ModuleRemoved), reads owner address via the contract's owner() function, reads privileged function signatures by analyzing function selectors, reads event logs by scanning for module-related events, reads transaction history via provider.getTransactionCount(contract), and reads module activation and deactivation status via the contract's module management functions. 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 permissions the module has, who granted them, what functions the module can call, and the risks of those permissions — while stating plainly that it cannot detect if a module's permissioned actions are being used maliciously beyond the registered permissions, cannot detect off-chain social engineering attacks or governance manipulation, and cannot guarantee that a module's permissions will not be changed in a future upgrade. The AI response is capped at 1,024 tokens to ensure concise, focused module permission assessments. All computed values are guarded against negative numbers — if a role count or function count appears invalid, the tool flags it rather than displaying nonsensical values.

WHAT IT CANNOT SEE

This tool cannot detect if a module's permissioned actions are being used maliciously beyond the registered permissions. It cannot detect off-chain social engineering attacks or governance manipulation. It cannot guarantee that a module's permissions will not be changed in a future upgrade. It cannot detect modules that are registered but have hidden or off-chain functionality. The AI explanation is generated from on-chain data only and cannot detect hidden module functionality, off-chain actions, or social engineering attacks. It cannot predict whether a module's permissions will be changed or revoked in the future. The tool does not continuously monitor module permissions; each analysis is a snapshot at the time of the lookup. It cannot detect delayed permission changes, hidden modules, 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 module safety or permission correctness.

PLEASE NOTE

Module Permission 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. Module permissions carry significant risk including privilege escalation, fund access, and governance bypass. 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.