{"id":18499143,"url":"https://github.com/moonstream-to/inspector-facet","last_synced_at":"2025-04-09T01:31:34.874Z","repository":{"id":40328231,"uuid":"481960940","full_name":"moonstream-to/inspector-facet","owner":"moonstream-to","description":"Inspector Facet - Inspection utility for EIP2535 Diamond proxies","archived":false,"fork":false,"pushed_at":"2024-10-25T11:52:25.000Z","size":41,"stargazers_count":17,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-03T08:51:34.600Z","etag":null,"topics":["blockchain","brownie","cli","data-analysis","developer-tools","eip2535","eth-brownie","ethereum","foundry","hacktoberfest","hardhat","library","pypi","python","smart-contracts","web3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moonstream-to.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-15T13:05:52.000Z","updated_at":"2024-10-25T11:50:12.000Z","dependencies_parsed_at":"2022-08-09T17:20:59.017Z","dependency_job_id":null,"html_url":"https://github.com/moonstream-to/inspector-facet","commit_stats":null,"previous_names":["moonstream-to/inspector-facet","bugout-dev/inspector-facet"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moonstream-to%2Finspector-facet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moonstream-to%2Finspector-facet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moonstream-to%2Finspector-facet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moonstream-to%2Finspector-facet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moonstream-to","download_url":"https://codeload.github.com/moonstream-to/inspector-facet/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247956552,"owners_count":21024570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","brownie","cli","data-analysis","developer-tools","eip2535","eth-brownie","ethereum","foundry","hacktoberfest","hardhat","library","pypi","python","smart-contracts","web3"],"created_at":"2024-11-06T13:44:48.770Z","updated_at":"2025-04-09T01:31:34.530Z","avatar_url":"https://github.com/moonstream-to.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Inspector Facet\n\n\u003ca href=\"https://media.giphy.com/media/14mgxYFJHXGmoo/giphy.gif\" target=\"_blank\"\u003e\u003cimg src=\"https://media.giphy.com/media/14mgxYFJHXGmoo/giphy.gif\" /\u003e\u003c/a\u003e\n\nA tool that allows you to inspect deployed [EIP-2535 Diamond proxy](https://eips.ethereum.org/EIPS/eip-2535)\ncontracts from your command line.\n\nInspector Facet was inspired by [Louper.dev](https://louper.dev/) ([GitHub](https://github.com/mark3labs/louper-v2)).\n\nInspector Facet uses side information about facet ABIs to match the selectors that a Diamond proxy\nis serving to human-understandable information about the facets and the functions.\n\nWe support side information obtained from:\n\n- [x] [brownie](https://github.com/eth-brownie/brownie) build artifacts\n- [x] [foundry](https://github.com/foundry-rs/foundry) build artifacts\n- [x] [hardhat](https://hardhat.org/) build artifacts\n- [ ] Etherscan/Polygonscan/etc.\n\nInspector Facet can build a complete audit log of all Diamond-related operations on an EIP2535 proxy\ncontract. Use this functionality with the `--timeline` argument.\n\n### Installation\n\nInspector Facet is written in Python 3 and is distributed using PyPI: https://pypi.org/project/inspector-facet/\n\nTo install Inspector Facet, run:\n\n```bash\npip install inspector-facet\n```\n\n### Usage\n\n```bash\ninspector-facet --help\n```\n\n\u003ca href=\"https://asciinema.org/a/487856\" target=\"_blank\"\u003e\u003cimg src=\"https://asciinema.org/a/487856.svg\" /\u003e\u003c/a\u003e\n\nTo use Inspector Facet:\n\n#### With a `brownie` project\n\nThe following command produces human-readable output:\n\n```bash\ninspector-facet \\\n    --network \u003cbrownie network name for blockchain\u003e \\\n    --address \u003caddress of diamond contract\u003e \\\n    --project \u003cpath to brownie project\u003e \\\n    --format human\n```\n\nThe following command produces JSON output and can be used to inspect a Diamond contract programatically\n(e.g. as part of a CI/CD pipeline):\n```bash\ninspector-facet \\\n    --network \u003cbrownie network name for blockchain\u003e \\\n    --address \u003caddress of diamond contract\u003e \\\n    --project \u003cpath to brownie project\u003e \\\n    --format json\n```\n\n#### With a `foundry` project\n\nThe following command produces human-readable output:\n\n```bash\ninspector-facet \\\n    --network \u003cbrownie network name for blockchain\u003e \\\n    --address \u003caddress of diamond contract\u003e \\\n    --project \u003cpath to foundry project\u003e \\\n    --foundry \\\n    --format human\n```\n\nThe following command produces JSON output and can be used to inspect a Diamond contract programatically\n(e.g. as part of a CI/CD pipeline):\n```bash\ninspector-facet \\\n    --network \u003cbrownie network name for blockchain\u003e \\\n    --address \u003caddress of diamond contract\u003e \\\n    --project \u003cpath to foundry project\u003e \\\n    --foundry \\\n    --format json\n```\n\n#### With a `hardhat` project\n\n```bash\ninspector-facet \\\n    --network \u003cbrownie network name for blockchain\u003e \\\n    --address \u003caddress of diamond contract\u003e \\\n    --project \u003cpath to foundry project\u003e \\\n    --hardhat \\\n    --format human\n```\n\nThe following command produces JSON output and can be used to inspect a Diamond contract programatically\n(e.g. as part of a CI/CD pipeline):\n```bash\ninspector-facet \\\n    --network \u003cbrownie network name for blockchain\u003e \\\n    --address \u003caddress of diamond contract\u003e \\\n    --project \u003cpath to foundry project\u003e \\\n    --hardhat \\\n    --format json\n```\n\n#### Non-standard build directories\n\nThe `--build-dir` command allows you to specify the name of the build directory in your `brownie` or\n`foundry` project in case you aren't using the standard directories (`build/` for `brownie` and `out/` for `foundry`).\n\n\n#### To build an audit log of Diamond operations on an EIP2535 proxy contract\n\nTo build an audit log, you will need to crawl `DiamondCut` events from the blockchain. You can do this using [`moonworm`](https://github.com/bugout-dev/moonworm).\n\nFirst, you will need to install `moonworm`:\n\n```bash\npip install moonworm\n```\n\nThis should be done in a separate Python environment from `inspector-facet` because `brownie` pins its dependencies\nand doesn't play nice with other libraries ([GitHub issue](https://github.com/eth-brownie/brownie/issues/1516)).\n\nOnce `moonworm` is installed, you can find the deployment block for your contract:\n\n```bash\nmoonworm find-deployment -w \u003cJSON RPC URL for blockchain node\u003e -c \u003ccontract address\u003e -t 0.5\n```\n\nSave the output of this command as `START_BLOCK`.\n\nThen crawl the `DiamondCut` event data:\n\n```bash\nmoonworm watch \\\n  -i inspector_facet/abis/DiamondCutFacetABI.json \\\n  -w \u003cJSON RPC URL for blockchain node\u003e \\\n  -c \u003ccontract address\u003e \\\n  --start $START_BLOCK \\\n  --end \u003ccurrent block number\u003e \\\n  --only-events \\\n  -o \u003coutput filename\u003e \\\n  --min-blocks-batch 1000 \\\n  --max-blocks-batch 1000000\n```\n\nIf you are crawling data from a POA chain (like Polygon), add `--poa` to the command above.\n\nThen, invoke `inspector-facet` as:\n\n```bash\ninspector-facet \\\n  --crawldata \u003coutput filename\u003e \\\n  --project \u003cpath to brownie project (should contain build artifacts in build/contracts)\u003e \\\n  --format human \\\n  --timeline\n```\n\n### Connecting to a blockchain\n\nInternally, Inspector Facet uses [`brownie`](https://github.com/eth-brownie/brownie) to work with any\nEthereum-based blockchain. When you use `inspector-facet`, even with a `hardhat` project, `inspector-facet`\nwill still use `brownie` to interact with any blockchain.\n\nAny `inspector-facet` command that calls out to a blockchain will take a `-n/--network` argument. The value\nof this argument must be the name of a `brownie` network configured in your Python environment.\n\n`brownie` is a dependency of `inspector-facet` and is automatically installed when you install `inspector-facet`.\n\nTo see a list of available `brownie` networks, activate the Python environment in which you installed\n`inspector-facet` and run:\n\n```bash\nbrownie networks list\n```\n\nThe output will look like this (truncated for brevity):\n\n```\n$ brownie networks list\n\nBrownie v1.17.2 - Python development framework for Ethereum\n\nThe following networks are declared:\n\nEthereum\n  ├─Mainnet (Infura): mainnet\n  ├─Ropsten (Infura): ropsten\n  ├─Rinkeby (Infura): rinkeby\n  ├─Goerli (Infura): goerli\n  └─Kovan (Infura): kovan\n\nEthereum Classic\n  ├─Mainnet: etc\n  └─Kotti: kotti\n\nArbitrum\n  └─Mainnet: arbitrum-main\n...\n```\n\nTo view the details for any particular network, use:\n\n```bash\nbrownie networks modify $NETWORK\n```\n\nFor example:\n\n```\n$ brownie networks modify mainnet\n\n$ brownie networks modify mainnet\nBrownie v1.17.2 - Python development framework for Ethereum\n\nSUCCESS: Network 'Mainnet (Infura)' has been modified\n  └─Mainnet (Infura)\n    ├─id: mainnet\n    ├─chainid: 1\n    ├─explorer: https://api.etherscan.io/api\n    ├─host: https://mainnet.infura.io/v3/$WEB3_INFURA_PROJECT_ID\n    └─multicall2: 0x5BA1e12693Dc8F9c48aAD8770482f4739bEeD696\n```\n\nIf you want to connect to this network, using Infura, all you have to do is set your `WEB3_INFURA_PROJECT_ID`\nenvironment variable (get this information from your project dashboard on Infura) and set `--network mainnet`\nwhen you invoke `inspector-facet`.\n\nFor networks which have publicly available nodes, it's even more straightforward:\n\n```\n$ brownie networks modify etc\nBrownie v1.17.2 - Python development framework for Ethereum\n\nSUCCESS: Network 'Mainnet' has been modified\n  └─Mainnet\n    ├─id: etc\n    ├─chainid: 61\n    ├─explorer: https://blockscout.com/etc/mainnet/api\n    └─host: https://www.ethercluster.com/etc\n```\n\nYou don't need any additional environment variables.\n\n#### Adding a custom network\n\nTo add your own network, use the `brownie networks add` command.\n\nThe signature for this command is:\n\n```\nbrownie networks add \u003clabel\u003e \u003cnetwork-name\u003e chainid=\u003cchain ID for network\u003e host=\u003cJSON RPC endpoint\u003e explorer=\u003cAPI URL for blockchain explorer\u003e\n```\n\nThe `\u003clabel\u003e` is purely for organizational purposes and can be set to whatever string you want.\n\nFor example, if you wanted to add the public Polygon RPC service as a network, you would do:\n\n```bash\nbrownie networks add Polygon matic chainid=137 host=https://polygon-rpc.com explorer=https://api.polygonscan.com/api\n```\n\n### Support\n\nYou can get help in any of the following ways:\n\n1. [File an issue](https://github.com/bugout-dev/inspector-facet/issues/new)\n2. Ask for help on [Moonstream Discord](https://discord.gg/K56VNUQGvA)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoonstream-to%2Finspector-facet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoonstream-to%2Finspector-facet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoonstream-to%2Finspector-facet/lists"}