# Woke
Woke is a Python-based development and testing framework for Solidity.
Features:
- **Testing framework** - a testing framework for Solidity smart contracts with Python-native equivalents of Solidity types and blazing fast execution.
- **Fuzzer** - a property-based fuzzer for Solidity smart contracts that allows testers to write their fuzz tests in Python.
- **Vulnerability detectors**
- **LSP server**
## Dependencies
- [Python](https://www.python.org/downloads/release/python-3910/) (version 3.7 or higher)
- Rosetta must be enabled on Apple Silicon (M1 & M2) Macs
> :warning: Python 3.11 is experimentally supported.
## Installation
via `pip`
```shell
pip3 install woke
```
## Documentation & Contribution
Woke documentation can be found [here](https://ackeeblockchain.com/woke/docs/latest).
There you can also find a section on [contributing](https://ackeeblockchain.com/woke/docs/latest/contributing/).
## Discovered vulnerabilities
| Vulnerability | Severity | Project | Method | Discovered by | Resources |
|-------------------------------------------------|----------|---------|------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Profit & loss accounted twice | Critical | IPOR | Fuzz test | Ackee Blockchain | [Woke tests](https://github.com/Ackee-Blockchain/tests-ipor/blob/main/tests/test_fuzz.py) |
| Console permanent denial of service | High | Brahma | Fuzz test | Ackee Blockchain | [Report](https://github.com/Ackee-Blockchain/public-audit-reports/blob/master/2023/ackee-blockchain-brahma-console-v2-report.pdf) |
| Swap unwinding formula error | High | IPOR | Fuzz test | Ackee Blockchain | [Woke tests](https://github.com/Ackee-Blockchain/tests-ipor/blob/main/tests/test_fuzz.py) |
| Swap unwinding fee accounted twice | High | IPOR | Fuzz test | Ackee Blockchain | [Woke tests](https://github.com/Ackee-Blockchain/tests-ipor/blob/main/tests/test_fuzz.py) |
| Incorrect event data | High | Solady | Integration test | Ackee Blockchain | [Report](https://github.com/Ackee-Blockchain/public-audit-reports/blob/master/2023/ackee-blockchain-solady-report.pdf), [Woke tests](https://github.com/Ackee-Blockchain/tests-solady/blob/main/tests/test_erc1155.py) |
| `INTEREST_FROM_STRATEGY_BELOW_ZERO` reverts DoS | Medium | IPOR | Fuzz test | Ackee Blockchain | [Woke tests](https://github.com/Ackee-Blockchain/tests-ipor/blob/main/tests/test_fuzz.py) |
| Inaccurate hypothetical interest formula | Medium | IPOR | Fuzz test | Ackee Blockchain | [Woke tests](https://github.com/Ackee-Blockchain/tests-ipor/blob/main/tests/test_fuzz.py) |
| Swap unwinding fee normalization error | Medium | IPOR | Fuzz test | Ackee Blockchain | [Woke tests](https://github.com/Ackee-Blockchain/tests-ipor/blob/main/tests/test_fuzz.py) |
| Missing receive function | Medium | Axelar | Fuzz test | Ackee Blockchain | [Woke tests](https://github.com/Ackee-Blockchain/tests-axelar-interchain-governance-executor/blob/main/tests/test_fuzz.py) |
## Features
### Testing framework
See [examples](examples) and [documentation](https://ackeeblockchain.com/woke/docs/latest/testing-framework/overview) for more information.
Writing tests is as simple as:
```python
from woke.testing import *
from pytypes.contracts.Counter import Counter
@default_chain.connect()
def test_counter():
default_chain.set_default_accounts(default_chain.accounts[0])
counter = Counter.deploy()
assert counter.count() == 0
counter.increment()
assert counter.count() == 1
```
### Fuzzer
Fuzzer builds on top of the testing framework and allows efficient fuzz testing of Solidity smart contracts.
```python
from woke.testing import *
from woke.testing.fuzzing import *
from pytypes.contracts.Counter import Counter
class CounterTest(FuzzTest):
def pre_sequence(self) -> None:
self.counter = Counter.deploy()
self.count = 0
@flow()
def increment(self) -> None:
self.counter.increment()
self.count += 1
@flow()
def decrement(self) -> None:
with may_revert(Panic(PanicCodeEnum.UNDERFLOW_OVERFLOW)) as e:
self.counter.decrement()
if e.value is not None:
assert self.count == 0
else:
self.count -= 1
@invariant(period=10)
def count(self) -> None:
assert self.counter.count() == self.count
@default_chain.connect()
def test_counter():
default_chain.set_default_accounts(default_chain.accounts[0])
CounterTest().run(sequences_count=30, flows_count=100)
```
### Vulnerability detectors
Vulnerability detectors can be run using:
```shell
woke detect
```
### LSP server
Woke implements an [LSP](https://microsoft.github.io/language-server-protocol/) server for Solidity. The only currently supported communication channel is TCP.
Woke LSP server can be run using:
```shell
woke lsp
```
Or with an optional --port argument (default 65432):
```shell
woke lsp --port 1234
```
All LSP server features can be found in the [documentation](https://ackeeblockchain.com/woke/docs/latest/language-server/).
## License
This project is licensed under the [ISC license](https://github.com/Ackee-Blockchain/woke/blob/main/LICENSE).
## Partners
RockawayX | Coinbase
:-------------------------:|:-------------------------:
[](https://rockawayx.com/) | [](https://www.coinbase.com/)
Raw data
{
"_id": null,
"home_page": "https://ackeeblockchain.com",
"name": "woke",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.9,<4.0.0",
"maintainer_email": "",
"keywords": "ethereum,solidity,security,testing,development,framework,audit",
"author": "Ackee Blockchain",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/4d/20/eb43edcfae307a4e541af94f5f82a1a1fec86d8af402dfc98ecef8656e7d/woke-3.6.1.tar.gz",
"platform": null,
"description": "# Woke\n\nWoke is a Python-based development and testing framework for Solidity.\n\nFeatures:\n\n- **Testing framework** - a testing framework for Solidity smart contracts with Python-native equivalents of Solidity types and blazing fast execution.\n\n- **Fuzzer** - a property-based fuzzer for Solidity smart contracts that allows testers to write their fuzz tests in Python.\n\n- **Vulnerability detectors**\n\n- **LSP server**\n\n## Dependencies\n\n- [Python](https://www.python.org/downloads/release/python-3910/) (version 3.7 or higher)\n- Rosetta must be enabled on Apple Silicon (M1 & M2) Macs\n\n> :warning: Python 3.11 is experimentally supported.\n\n## Installation\n\nvia `pip`\n\n```shell\npip3 install woke\n```\n\n## Documentation & Contribution\n\nWoke documentation can be found [here](https://ackeeblockchain.com/woke/docs/latest).\n\nThere you can also find a section on [contributing](https://ackeeblockchain.com/woke/docs/latest/contributing/).\n\n## Discovered vulnerabilities\n\n| Vulnerability | Severity | Project | Method | Discovered by | Resources |\n|-------------------------------------------------|----------|---------|------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Profit & loss accounted twice | Critical | IPOR | Fuzz test | Ackee Blockchain | [Woke tests](https://github.com/Ackee-Blockchain/tests-ipor/blob/main/tests/test_fuzz.py) |\n| Console permanent denial of service | High | Brahma | Fuzz test | Ackee Blockchain | [Report](https://github.com/Ackee-Blockchain/public-audit-reports/blob/master/2023/ackee-blockchain-brahma-console-v2-report.pdf) |\n| Swap unwinding formula error | High | IPOR | Fuzz test | Ackee Blockchain | [Woke tests](https://github.com/Ackee-Blockchain/tests-ipor/blob/main/tests/test_fuzz.py) |\n| Swap unwinding fee accounted twice | High | IPOR | Fuzz test | Ackee Blockchain | [Woke tests](https://github.com/Ackee-Blockchain/tests-ipor/blob/main/tests/test_fuzz.py) |\n| Incorrect event data | High | Solady | Integration test | Ackee Blockchain | [Report](https://github.com/Ackee-Blockchain/public-audit-reports/blob/master/2023/ackee-blockchain-solady-report.pdf), [Woke tests](https://github.com/Ackee-Blockchain/tests-solady/blob/main/tests/test_erc1155.py) |\n| `INTEREST_FROM_STRATEGY_BELOW_ZERO` reverts DoS | Medium | IPOR | Fuzz test | Ackee Blockchain | [Woke tests](https://github.com/Ackee-Blockchain/tests-ipor/blob/main/tests/test_fuzz.py) |\n| Inaccurate hypothetical interest formula | Medium | IPOR | Fuzz test | Ackee Blockchain | [Woke tests](https://github.com/Ackee-Blockchain/tests-ipor/blob/main/tests/test_fuzz.py) |\n| Swap unwinding fee normalization error | Medium | IPOR | Fuzz test | Ackee Blockchain | [Woke tests](https://github.com/Ackee-Blockchain/tests-ipor/blob/main/tests/test_fuzz.py) |\n| Missing receive function | Medium | Axelar | Fuzz test | Ackee Blockchain | [Woke tests](https://github.com/Ackee-Blockchain/tests-axelar-interchain-governance-executor/blob/main/tests/test_fuzz.py) |\n\n## Features\n\n### Testing framework\n\nSee [examples](examples) and [documentation](https://ackeeblockchain.com/woke/docs/latest/testing-framework/overview) for more information.\n\nWriting tests is as simple as:\n\n```python\nfrom woke.testing import *\nfrom pytypes.contracts.Counter import Counter\n\n@default_chain.connect()\ndef test_counter():\n default_chain.set_default_accounts(default_chain.accounts[0])\n\n counter = Counter.deploy()\n assert counter.count() == 0\n\n counter.increment()\n assert counter.count() == 1\n```\n\n### Fuzzer\n\nFuzzer builds on top of the testing framework and allows efficient fuzz testing of Solidity smart contracts.\n\n```python\nfrom woke.testing import *\nfrom woke.testing.fuzzing import *\nfrom pytypes.contracts.Counter import Counter\n\nclass CounterTest(FuzzTest):\n def pre_sequence(self) -> None:\n self.counter = Counter.deploy()\n self.count = 0\n\n @flow()\n def increment(self) -> None:\n self.counter.increment()\n self.count += 1\n\n @flow()\n def decrement(self) -> None:\n with may_revert(Panic(PanicCodeEnum.UNDERFLOW_OVERFLOW)) as e:\n self.counter.decrement()\n\n if e.value is not None:\n assert self.count == 0\n else:\n self.count -= 1\n\n @invariant(period=10)\n def count(self) -> None:\n assert self.counter.count() == self.count\n\n@default_chain.connect()\ndef test_counter():\n default_chain.set_default_accounts(default_chain.accounts[0])\n CounterTest().run(sequences_count=30, flows_count=100)\n```\n\n### Vulnerability detectors\n\nVulnerability detectors can be run using:\n```shell\nwoke detect\n```\n\n### LSP server\n\nWoke implements an [LSP](https://microsoft.github.io/language-server-protocol/) server for Solidity. The only currently supported communication channel is TCP.\n\nWoke LSP server can be run using:\n\n```shell\nwoke lsp\n```\n\nOr with an optional --port argument (default 65432):\n\n```shell\nwoke lsp --port 1234\n```\n\nAll LSP server features can be found in the [documentation](https://ackeeblockchain.com/woke/docs/latest/language-server/).\n\n## License\n\nThis project is licensed under the [ISC license](https://github.com/Ackee-Blockchain/woke/blob/main/LICENSE).\n\n## Partners\n\nRockawayX | Coinbase\n:-------------------------:|:-------------------------:\n[](https://rockawayx.com/) | [](https://www.coinbase.com/)\n\n\n\n\n\n\n",
"bugtrack_url": null,
"license": "ISC",
"summary": "Woke is a Python-based development and testing framework for Solidity.",
"version": "3.6.1",
"project_urls": {
"Announcement": "https://ackeeblockchain.com/blog/woke-our-development-and-testing-framework-for-solidity/",
"Documentation": "https://ackeeblockchain.com/woke/docs/latest",
"Homepage": "https://ackeeblockchain.com",
"Repository": "https://github.com/Ackee-Blockchain/woke",
"VS Code Extension": "https://marketplace.visualstudio.com/items?itemName=AckeeBlockchain.tools-for-solidity"
},
"split_keywords": [
"ethereum",
"solidity",
"security",
"testing",
"development",
"framework",
"audit"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "50a4d145aa0774e9c4256e61fcda451e9db1d9fca1371f34e24cf9b314113128",
"md5": "b9bb8a0defa2ac7bc54adcdc6ff3322a",
"sha256": "25a1d9c9c41544b2ab8f078a9797b09e543b2368aa56fe5762deae908839c561"
},
"downloads": -1,
"filename": "woke-3.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b9bb8a0defa2ac7bc54adcdc6ff3322a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7.9,<4.0.0",
"size": 404345,
"upload_time": "2023-10-25T08:42:10",
"upload_time_iso_8601": "2023-10-25T08:42:10.164011Z",
"url": "https://files.pythonhosted.org/packages/50/a4/d145aa0774e9c4256e61fcda451e9db1d9fca1371f34e24cf9b314113128/woke-3.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4d20eb43edcfae307a4e541af94f5f82a1a1fec86d8af402dfc98ecef8656e7d",
"md5": "5ad72c5de8d01ec5fbcce348cb8e4efb",
"sha256": "021d03cec507879b92654addd005d9d8b45112b0dcec278dc3109205085ef793"
},
"downloads": -1,
"filename": "woke-3.6.1.tar.gz",
"has_sig": false,
"md5_digest": "5ad72c5de8d01ec5fbcce348cb8e4efb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.9,<4.0.0",
"size": 293467,
"upload_time": "2023-10-25T08:42:12",
"upload_time_iso_8601": "2023-10-25T08:42:12.578255Z",
"url": "https://files.pythonhosted.org/packages/4d/20/eb43edcfae307a4e541af94f5f82a1a1fec86d8af402dfc98ecef8656e7d/woke-3.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-25 08:42:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Ackee-Blockchain",
"github_project": "woke",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "woke"
}
JSON
