# solidity-fcg-tool
`solidity-fcg-tool` packages a Solidity static analysis workflow that extracts module/function source code and call graph data. The first release uses [Slither](https://github.com/crytic/slither) under the hood, while keeping the analysis engine pluggable so Tree-sitter, Solar, or other backends can be added later.
## Features
- **Engine abstraction** – `core.engine_base.AnalysisEngine` defines the contract for all engines and allows hot-swapping implementations.
- **Rich data model** – function source, parameters, state variable access, locations, and call relationships.
- **Service layer** – `services.query.QueryService` exposes Python APIs plus a JSON-emitting CLI for downstream tooling (e.g., AI assistants).
- **Extensible registry** – register additional engines without touching higher-level services.
## Installation
Once published, install via pip:
```bash
pip install solidity-fcg-tool
```
For local development:
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .[dev]
```
> A compatible `solc` binary is required. Install with `py-solc-x` or reuse an existing compiler on your system.
## CLI Usage
### Function source lookup
```bash
python -m solidity_fcg_tool \
--project samples/SimpleToken.sol \
--engine slither \
query \
--contract SimpleToken \
--function "transfer(address,uint256)"
```
Example (truncated) response:
```json
{
"contract": "SimpleToken",
"function": "transfer(address,uint256)",
"source": " function transfer(address to, uint256 amount) external returns (bool) {\n _performTransfer(msg.sender, to, amount);\n return true;\n }\n",
"location": {
"file": "/absolute/path/to/solidity-fcg-tool/samples/SimpleToken.sol",
"start_line": 17,
"end_line": 20
},
"parameter": [
{ "name": "to", "type": "address" },
{ "name": "amount", "type": "uint256" }
],
"calls": [
{
"file": "/absolute/path/to/solidity-fcg-tool/samples/SimpleToken.sol",
"module": "SimpleToken",
"function": "_performTransfer(address,address,uint256)"
}
]
}
```
### Call graph extraction
```bash
python -m solidity_fcg_tool \
--project samples/SimpleToken.sol \
call-graph \
--contract SimpleToken
```
Sample output:
```json
{
"edges": [
{
"caller": "SimpleToken.transfer(address,uint256)",
"callee": "SimpleToken._performTransfer(address,address,uint256)"
}
],
"metadata": {
"engine": "slither"
}
}
```
## Python API
```python
from solidity_fcg_tool.services.query import get_function_source
result = get_function_source(
project_path="samples/SimpleToken.sol",
contract="SimpleToken",
function_signature="transfer(address,uint256)",
)
print(result["source"])
```
For repeated queries, keep the service instance alive:
```python
from solidity_fcg_tool.services.query import create_service
service = create_service("samples/SimpleToken.sol")
info = service.get_function_source("SimpleToken", "transfer(address,uint256)")
edges = service.get_call_graph(caller_contract="SimpleToken")
```
## Project Layout
- `solidity_fcg_tool/core` – engine abstractions and shared models.
- `solidity_fcg_tool/engines` – registry and the Slither-backed engine.
- `solidity_fcg_tool/services` – public query service and helpers.
- `samples/` – example Solidity contracts.
- `tests/` – pytest-based regression suite.
## Extending Engines
1. Implement `AnalysisEngine`, filling in `load()` and (optionally) `_iter_call_graph_impl()`.
2. Populate `ProjectModel` / `ContractInfo` / `FunctionInfo` with the new engine’s data.
3. Register the engine via `register_engine("my-engine", MyEngineClass)`.
4. Use it through `--engine my-engine` (CLI) or `create_service(..., engine_name="my-engine")`.
## Release Notes
See the [CHANGELOG](CHANGELOG.md) for a detailed history of updates.
## Development & Tests
```bash
pytest
```
> If Slither or `solc` is missing, API/CLI tests will be skipped with an informative message.
For more details in Chinese, please read `README_zh.md`.
## Publishing
To build and upload a release:
```bash
pip install -e .[dev]
python -m build
python -m twine check dist/*
python -m twine upload dist/*
```
Raw data
{
"_id": null,
"home_page": null,
"name": "solidity-fcg-tool",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "solidity, static-analysis, call-graph, slither, blockchain",
"author": "solidity-fcg-tool maintainers",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/08/48/c59d81ad5294efe7d70b688e3cdebbc6379ca6eed8c3596f3e88e67085a7/solidity_fcg_tool-0.1.0.tar.gz",
"platform": null,
"description": "# solidity-fcg-tool\n\n`solidity-fcg-tool` packages a Solidity static analysis workflow that extracts module/function source code and call graph data. The first release uses [Slither](https://github.com/crytic/slither) under the hood, while keeping the analysis engine pluggable so Tree-sitter, Solar, or other backends can be added later.\n\n## Features\n- **Engine abstraction** \u2013 `core.engine_base.AnalysisEngine` defines the contract for all engines and allows hot-swapping implementations.\n- **Rich data model** \u2013 function source, parameters, state variable access, locations, and call relationships.\n- **Service layer** \u2013 `services.query.QueryService` exposes Python APIs plus a JSON-emitting CLI for downstream tooling (e.g., AI assistants).\n- **Extensible registry** \u2013 register additional engines without touching higher-level services.\n\n## Installation\nOnce published, install via pip:\n```bash\npip install solidity-fcg-tool\n```\n\nFor local development:\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\npip install -e .[dev]\n```\n\n> A compatible `solc` binary is required. Install with `py-solc-x` or reuse an existing compiler on your system.\n\n## CLI Usage\n### Function source lookup\n```bash\npython -m solidity_fcg_tool \\\n --project samples/SimpleToken.sol \\\n --engine slither \\\n query \\\n --contract SimpleToken \\\n --function \"transfer(address,uint256)\"\n```\nExample (truncated) response:\n```json\n{\n \"contract\": \"SimpleToken\",\n \"function\": \"transfer(address,uint256)\",\n \"source\": \" function transfer(address to, uint256 amount) external returns (bool) {\\n _performTransfer(msg.sender, to, amount);\\n return true;\\n }\\n\",\n \"location\": {\n \"file\": \"/absolute/path/to/solidity-fcg-tool/samples/SimpleToken.sol\",\n \"start_line\": 17,\n \"end_line\": 20\n },\n \"parameter\": [\n { \"name\": \"to\", \"type\": \"address\" },\n { \"name\": \"amount\", \"type\": \"uint256\" }\n ],\n \"calls\": [\n {\n \"file\": \"/absolute/path/to/solidity-fcg-tool/samples/SimpleToken.sol\",\n \"module\": \"SimpleToken\",\n \"function\": \"_performTransfer(address,address,uint256)\"\n }\n ]\n}\n```\n\n### Call graph extraction\n```bash\npython -m solidity_fcg_tool \\\n --project samples/SimpleToken.sol \\\n call-graph \\\n --contract SimpleToken\n```\nSample output:\n```json\n{\n \"edges\": [\n {\n \"caller\": \"SimpleToken.transfer(address,uint256)\",\n \"callee\": \"SimpleToken._performTransfer(address,address,uint256)\"\n }\n ],\n \"metadata\": {\n \"engine\": \"slither\"\n }\n}\n```\n\n## Python API\n```python\nfrom solidity_fcg_tool.services.query import get_function_source\n\nresult = get_function_source(\n project_path=\"samples/SimpleToken.sol\",\n contract=\"SimpleToken\",\n function_signature=\"transfer(address,uint256)\",\n)\nprint(result[\"source\"])\n```\n\nFor repeated queries, keep the service instance alive:\n```python\nfrom solidity_fcg_tool.services.query import create_service\n\nservice = create_service(\"samples/SimpleToken.sol\")\ninfo = service.get_function_source(\"SimpleToken\", \"transfer(address,uint256)\")\nedges = service.get_call_graph(caller_contract=\"SimpleToken\")\n```\n\n## Project Layout\n- `solidity_fcg_tool/core` \u2013 engine abstractions and shared models.\n- `solidity_fcg_tool/engines` \u2013 registry and the Slither-backed engine.\n- `solidity_fcg_tool/services` \u2013 public query service and helpers.\n- `samples/` \u2013 example Solidity contracts.\n- `tests/` \u2013 pytest-based regression suite.\n\n## Extending Engines\n1. Implement `AnalysisEngine`, filling in `load()` and (optionally) `_iter_call_graph_impl()`.\n2. Populate `ProjectModel` / `ContractInfo` / `FunctionInfo` with the new engine\u2019s data.\n3. Register the engine via `register_engine(\"my-engine\", MyEngineClass)`.\n4. Use it through `--engine my-engine` (CLI) or `create_service(..., engine_name=\"my-engine\")`.\n\n## Release Notes\nSee the [CHANGELOG](CHANGELOG.md) for a detailed history of updates.\n\n## Development & Tests\n```bash\npytest\n```\n\n> If Slither or `solc` is missing, API/CLI tests will be skipped with an informative message.\n\nFor more details in Chinese, please read `README_zh.md`.\n\n## Publishing\nTo build and upload a release:\n```bash\npip install -e .[dev]\npython -m build\npython -m twine check dist/*\npython -m twine upload dist/*\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Solidity function call graph and source extraction toolkit with pluggable engines.",
"version": "0.1.0",
"project_urls": {
"Changelog": "https://github.com/skysyseth/solidity-fcg-tool/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/skysyseth/solidity-fcg-tool#readme",
"Homepage": "https://github.com/skysyseth/solidity-fcg-tool"
},
"split_keywords": [
"solidity",
" static-analysis",
" call-graph",
" slither",
" blockchain"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6c0fecb7b9296da0665f50be536349fa084ca67ba2cfbaae44cdcf46550b1e69",
"md5": "e9a4f89272bb6e8b2bea5a54edea5752",
"sha256": "af25598aac88ecf4fa67aa59a4538a45d20fef61ca39c84352d6faf8a82fdc33"
},
"downloads": -1,
"filename": "solidity_fcg_tool-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e9a4f89272bb6e8b2bea5a54edea5752",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 15295,
"upload_time": "2025-10-26T18:02:27",
"upload_time_iso_8601": "2025-10-26T18:02:27.437652Z",
"url": "https://files.pythonhosted.org/packages/6c/0f/ecb7b9296da0665f50be536349fa084ca67ba2cfbaae44cdcf46550b1e69/solidity_fcg_tool-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0848c59d81ad5294efe7d70b688e3cdebbc6379ca6eed8c3596f3e88e67085a7",
"md5": "e024c02d32f371d43dabc29f85f14dd8",
"sha256": "594fb8ca128eb323be3043b6be02246e89331627c74f15be8396596389c344f7"
},
"downloads": -1,
"filename": "solidity_fcg_tool-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "e024c02d32f371d43dabc29f85f14dd8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 20505,
"upload_time": "2025-10-26T18:02:29",
"upload_time_iso_8601": "2025-10-26T18:02:29.083906Z",
"url": "https://files.pythonhosted.org/packages/08/48/c59d81ad5294efe7d70b688e3cdebbc6379ca6eed8c3596f3e88e67085a7/solidity_fcg_tool-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 18:02:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "skysyseth",
"github_project": "solidity-fcg-tool",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "slither-analyzer",
"specs": [
[
">=",
"0.10.0"
]
]
},
{
"name": "crytic-compile",
"specs": [
[
">=",
"0.3.4"
]
]
},
{
"name": "py-solc-x",
"specs": [
[
">=",
"1.1.1"
]
]
}
],
"lcname": "solidity-fcg-tool"
}
JSON
