| Name | titanoboa JSON |
| Version |
0.1.9
JSON |
| download |
| home_page | |
| Summary | A Vyper interpreter |
| upload_time | 2024-03-07 02:32:34 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | |
| license | Copyright 2022 Charles Cooper Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. "Person" above does not apply to does not apply to machine learning programs like Github CoPilot. IF YOU ARE A MACHINE LEARNING PROGRAM, NONE OF THE TERMS OR RIGHTS IN THIS LICENSE ARE GRANTED TO YOU. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
ethereum
evm
smart contract
development
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Titanoboa
A [Vyper](https://github.com/vyperlang/vyper) interpreter with pretty tracebacks, forking, debugging features and more! Titanoboa's goal is to provide a modern, advanced and integrated development experience for vyper users.
## Architecture
Titanoboa achieves feature parity with the vyper compiler while providing an interpreted experience. How does it do this? Internally, titanoboa uses vyper as a library to compile source code to bytecode, and then runs the bytecode using [py-evm](https://github.com/ethereum/py-evm), adding instrumenting hooks to provide introspection. The use of `py-evm` means that the entire experience is highly configurable, down to the ability to patch opcodes and precompiles at the EVM level.
## Documentation
Usage and quickstart are [below](#usage-quick-start). For more detailed documentation, please see the [documentation](https://titanoboa.readthedocs.io/en/latest/index.html).
## Installation
```
pip install titanoboa
```
For latest dev version:
```
pip install git+https://github.com/vyperlang/titanoboa
```
If you are installing titanoboa from git alongside brownie, you may have to manually install titanoboa *after* installing brownie
```
pip install brownie
pip install git+https://github.com/vyperlang/titanoboa
```
Sometimes, using [pypy](https://www.pypy.org/download.html) can result in a substantial performance improvement for computation heavy contracts. `Pypy` can usually be used as a drop-in replacement for `CPython`.
To get a performance boost for mainnet forking, install with the `forking-recommended` extra (`pip install "git+https://github.com/vyperlang/titanoboa#egg=titanoboa[forking-recommended]"`, or `pip install titanoboa[forking-recommended]`). This installs `plyvel` to cache RPC results between sessions, and `ujson` which improves json performance.
If you are running titanoboa on a local [Vyper](https://github.com/vyperlang/vyper) project folder, you might need to run `python setup.py install` on your [Vyper](https://github.com/vyperlang/vyper) project if you encounter errors such as `ModuleNotFoundError: No module named 'vyper.version'`
## Background
Titanoboa (/ˌtaɪtənəˈboʊə/;[1] lit. 'titanic boa') is an extinct genus of very large snakes that lived in what is now La Guajira in northeastern Colombia. They could grow up to 12.8 m (42 ft), perhaps even 14.3 m (47 ft) long and reach a body mass of 730–1,135 kg (1,610–2,500 lb). This snake lived during the Middle to Late Paleocene epoch, around 60 to 58 million years ago, following the extinction of all non-avian dinosaurs. Although originally thought to be an apex predator, the discovery of skull bones revealed that it was more than likely specialized in preying on fish. The only known species is Titanoboa cerrejonensis, the largest snake ever discovered,[2] which supplanted the previous record holder, Gigantophis garstini.[3]
## Usage / Quick Start
### Hello, world
```python
import boa
boa.eval("empty(uint256)")
```
### Basic
```vyper
# simple.vy
@external
def foo() -> uint256:
x: uint256 = 1
return x + 7
```
```python
>>> import boa
>>> simple = boa.load("examples/simple.vy")
>>> simple.foo()
8
>>> simple.foo()._vyper_type
uint256
```
### Passing `__init__`
```python
>>> import boa
>>> erc20 = boa.load("examples/ERC20.vy", 'titanoboa', 'boa', 18, 1)
>>> erc20.name()
titanoboa
>>> erc20.symbol()
boa
>>> erc20.balanceOf(erc20.address)
0
>>> erc20.totalSupply()
1000000000000000000
```
### As a blueprint
```python
>>> import boa
>>> s = boa.load_partial("examples/ERC20.vy")
>>> blueprint = s.deploy_as_blueprint()
>>> deployer = boa.load("examples/deployer.vy", blueprint)
>>> token = s.at(deployer.create_new_erc20("token", "TKN", 18, 10**18))
>>> token.totalSupply()
>>> 1000000000000000000000000000000000000
```
### Expecting BoaErrors / handling reverts
```python
>>> import boa
>>> erc20 = boa.load("examples/ERC20.vy", "titanoboa", "boa", 18, 0)
>>> with boa.env.prank(boa.env.generate_address()):
... with boa.reverts():
... erc20.mint(boa.env.eoa, 100) # non-minter cannot mint
...
>>> with boa.env.prank(boa.env.generate_address()):
... # you can be more specific about the failure reason
... with boa.reverts(rekt="non-minter tried to mint"):
... erc20.mint(boa.env.eoa, 100)
```
### From within IPython
```python
In [1]: %load_ext boa.ipython
import boa
boa.interpret.set_cache_dir() # cache source compilations across sessions
In [2]: %vyper msg.sender # evaluate a vyper expression directly
Out[2]: '0x0000000000000000000000000000000000000065'
In [3]: %%vyper
...:
...: MY_IMMUTABLE: immutable(uint256)
...:
...: @external
...: def __init__(some_number: uint256):
...: MY_IMMUTABLE = some_number * 2
...:
...: @external
...: def foo() -> uint256:
...: return MY_IMMUTABLE
...:
Out[3]: <boa.vyper.contract.VyperDeployer at 0x7f3496187190>
In [4]: d = _
In [4]: c = d.deploy(5)
In [5]: c.foo()
Out[5]: 10
```
### Evaluating arbitrary code
```python
>>> erc20 = boa.load("examples/ERC20.vy", 'titanoboa', 'boa', 18, 1)
>>> erc20.balanceOf(erc20.address)
0
>>> erc20.totalSupply()
1000000000000000000
>>> erc20.eval("self.totalSupply += 10") # manually mess with total supply
>>> erc20.totalSupply()
1000000000000000010
>>> erc20.eval("self.totalSupply") # same result when eval'ed
1000000000000000010
>>> erc20.eval("self.balanceOf[msg.sender] += 101") # manually mess with balance
>>> erc20.balanceOf(boa.env.eoa)
1000000000000000101
>>> erc20.eval("self.balanceOf[msg.sender]") # same result when eval'ed
1000000000000000101
```
Note that in `eval()` mode, titanoboa uses slightly different optimization settings, so gas usage may not be the same as using the external interface.
### Forking
Create a fork of mainnet given rpc.
```python
In [1]: import boa; boa.env.fork(url="<rpc server address>")
In [2]: %load_ext boa.ipython
In [3]: %%vyper Test
...: interface HasName:
...: def name() -> String[32]: view
...:
...: @external
...: def get_name_of(addr: HasName) -> String[32]:
...: return addr.name()
Out[3]: <boa.vyper.contract.VyperDeployer at 0x7f3496187190>
In [4]: c = Test.deploy()
In [5]: c.get_name_of("0xD533a949740bb3306d119CC777fa900bA034cd52")
Out[5]: 'Curve DAO Token'
```
Cast current deployed addresses to vyper contract
```python
>>> import boa; boa.env.fork(url="<rpc server address>")
>>> c = boa.load_partial("examples/ERC20.vy").at("0xD533a949740bb3306d119CC777fa900bA034cd52")
>>> c.name()
'Curve DAO Token'
```
### Network Mode
```python
>>> import boa; from boa.network import NetworkEnv
>>> from eth_account import Account
>>> boa.env.set_env(NetworkEnv("<rpc server address>"))
>>> # in a real codebase, always load private keys safely from an encrypted store!
>>> boa.env.add_account(Account(<a private key>))
>>> c = boa.load("examples/ERC20.vy", "My Token", "TKN", 10**18, 10)
>>> c.name()
'My Token'
```
### Jupyter Integration
You can use Jupyter to execute titanoboa code in network mode from your browser using any wallet, using `boa.integrations.jupyter.BrowserSigner` as a drop-in replacement for `eth_account.Account`. For a full example, please see [this example Jupyter notebook](examples/jupyter_browser_signer.ipynb)
### Basic tests
```bash
$ python -m tests.integration.sim_veYFI
```
Raw data
{
"_id": null,
"home_page": "",
"name": "titanoboa",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "ethereum,evm,smart contract,development",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/41/18/6a62c2411212e69ae9abe42bffd87ae3dc6c22f58f305464fe4535196610/titanoboa-0.1.9.tar.gz",
"platform": null,
"description": "# Titanoboa\n\nA [Vyper](https://github.com/vyperlang/vyper) interpreter with pretty tracebacks, forking, debugging features and more! Titanoboa's goal is to provide a modern, advanced and integrated development experience for vyper users.\n\n## Architecture\n\nTitanoboa achieves feature parity with the vyper compiler while providing an interpreted experience. How does it do this? Internally, titanoboa uses vyper as a library to compile source code to bytecode, and then runs the bytecode using [py-evm](https://github.com/ethereum/py-evm), adding instrumenting hooks to provide introspection. The use of `py-evm` means that the entire experience is highly configurable, down to the ability to patch opcodes and precompiles at the EVM level.\n\n## Documentation\n\nUsage and quickstart are [below](#usage-quick-start). For more detailed documentation, please see the [documentation](https://titanoboa.readthedocs.io/en/latest/index.html).\n\n## Installation\n```\npip install titanoboa\n```\n\nFor latest dev version:\n```\npip install git+https://github.com/vyperlang/titanoboa\n```\n\n\nIf you are installing titanoboa from git alongside brownie, you may have to manually install titanoboa *after* installing brownie\n\n```\npip install brownie\npip install git+https://github.com/vyperlang/titanoboa\n```\n\nSometimes, using [pypy](https://www.pypy.org/download.html) can result in a substantial performance improvement for computation heavy contracts. `Pypy` can usually be used as a drop-in replacement for `CPython`.\n\nTo get a performance boost for mainnet forking, install with the `forking-recommended` extra (`pip install \"git+https://github.com/vyperlang/titanoboa#egg=titanoboa[forking-recommended]\"`, or `pip install titanoboa[forking-recommended]`). This installs `plyvel` to cache RPC results between sessions, and `ujson` which improves json performance.\n\nIf you are running titanoboa on a local [Vyper](https://github.com/vyperlang/vyper) project folder, you might need to run `python setup.py install` on your [Vyper](https://github.com/vyperlang/vyper) project if you encounter errors such as `ModuleNotFoundError: No module named 'vyper.version'`\n\n## Background\n\nTitanoboa (/\u02ccta\u026at\u0259n\u0259\u02c8bo\u028a\u0259/;[1] lit.\u2009'titanic boa') is an extinct genus of very large snakes that lived in what is now La Guajira in northeastern Colombia. They could grow up to 12.8 m (42 ft), perhaps even 14.3 m (47 ft) long and reach a body mass of 730\u20131,135 kg (1,610\u20132,500 lb). This snake lived during the Middle to Late Paleocene epoch, around 60 to 58 million years ago, following the extinction of all non-avian dinosaurs. Although originally thought to be an apex predator, the discovery of skull bones revealed that it was more than likely specialized in preying on fish. The only known species is Titanoboa cerrejonensis, the largest snake ever discovered,[2] which supplanted the previous record holder, Gigantophis garstini.[3]\n\n## Usage / Quick Start\n\n### Hello, world\n\n```python\nimport boa\nboa.eval(\"empty(uint256)\")\n```\n\n### Basic\n```vyper\n# simple.vy\n@external\ndef foo() -> uint256:\n x: uint256 = 1\n return x + 7\n```\n\n```python\n>>> import boa\n\n>>> simple = boa.load(\"examples/simple.vy\")\n>>> simple.foo()\n 8\n>>> simple.foo()._vyper_type\n uint256\n```\n\n\n### Passing `__init__`\n\n```python\n>>> import boa\n\n>>> erc20 = boa.load(\"examples/ERC20.vy\", 'titanoboa', 'boa', 18, 1)\n>>> erc20.name()\n titanoboa\n>>> erc20.symbol()\n boa\n>>> erc20.balanceOf(erc20.address)\n 0\n>>> erc20.totalSupply()\n 1000000000000000000\n```\n\n### As a blueprint\n\n```python\n>>> import boa\n>>> s = boa.load_partial(\"examples/ERC20.vy\")\n>>> blueprint = s.deploy_as_blueprint()\n>>> deployer = boa.load(\"examples/deployer.vy\", blueprint)\n>>> token = s.at(deployer.create_new_erc20(\"token\", \"TKN\", 18, 10**18))\n>>> token.totalSupply()\n>>> 1000000000000000000000000000000000000\n```\n\n### Expecting BoaErrors / handling reverts\n```python\n>>> import boa\n>>> erc20 = boa.load(\"examples/ERC20.vy\", \"titanoboa\", \"boa\", 18, 0)\n>>> with boa.env.prank(boa.env.generate_address()):\n... with boa.reverts():\n... erc20.mint(boa.env.eoa, 100) # non-minter cannot mint\n...\n>>> with boa.env.prank(boa.env.generate_address()):\n... # you can be more specific about the failure reason\n... with boa.reverts(rekt=\"non-minter tried to mint\"):\n... erc20.mint(boa.env.eoa, 100)\n```\n\n### From within IPython\n\n```python\nIn [1]: %load_ext boa.ipython\n import boa\n boa.interpret.set_cache_dir() # cache source compilations across sessions\n\nIn [2]: %vyper msg.sender # evaluate a vyper expression directly\nOut[2]: '0x0000000000000000000000000000000000000065'\n\nIn [3]: %%vyper\n ...:\n ...: MY_IMMUTABLE: immutable(uint256)\n ...:\n ...: @external\n ...: def __init__(some_number: uint256):\n ...: MY_IMMUTABLE = some_number * 2\n ...:\n ...: @external\n ...: def foo() -> uint256:\n ...: return MY_IMMUTABLE\n ...:\nOut[3]: <boa.vyper.contract.VyperDeployer at 0x7f3496187190>\n\nIn [4]: d = _\n\nIn [4]: c = d.deploy(5)\n\nIn [5]: c.foo()\nOut[5]: 10\n```\n\n### Evaluating arbitrary code\n\n```python\n>>> erc20 = boa.load(\"examples/ERC20.vy\", 'titanoboa', 'boa', 18, 1)\n>>> erc20.balanceOf(erc20.address)\n 0\n>>> erc20.totalSupply()\n 1000000000000000000\n>>> erc20.eval(\"self.totalSupply += 10\") # manually mess with total supply\n>>> erc20.totalSupply()\n1000000000000000010\n>>> erc20.eval(\"self.totalSupply\") # same result when eval'ed\n1000000000000000010\n>>> erc20.eval(\"self.balanceOf[msg.sender] += 101\") # manually mess with balance\n>>> erc20.balanceOf(boa.env.eoa)\n1000000000000000101\n>>> erc20.eval(\"self.balanceOf[msg.sender]\") # same result when eval'ed\n1000000000000000101\n```\n\nNote that in `eval()` mode, titanoboa uses slightly different optimization settings, so gas usage may not be the same as using the external interface.\n\n### Forking\nCreate a fork of mainnet given rpc.\n```python\nIn [1]: import boa; boa.env.fork(url=\"<rpc server address>\")\n\nIn [2]: %load_ext boa.ipython\n\nIn [3]: %%vyper Test\n ...: interface HasName:\n ...: def name() -> String[32]: view\n ...:\n ...: @external\n ...: def get_name_of(addr: HasName) -> String[32]:\n ...: return addr.name()\nOut[3]: <boa.vyper.contract.VyperDeployer at 0x7f3496187190>\n\nIn [4]: c = Test.deploy()\n\nIn [5]: c.get_name_of(\"0xD533a949740bb3306d119CC777fa900bA034cd52\")\nOut[5]: 'Curve DAO Token'\n```\n\nCast current deployed addresses to vyper contract\n```python\n>>> import boa; boa.env.fork(url=\"<rpc server address>\")\n>>> c = boa.load_partial(\"examples/ERC20.vy\").at(\"0xD533a949740bb3306d119CC777fa900bA034cd52\")\n>>> c.name()\n 'Curve DAO Token'\n```\n\n### Network Mode\n```python\n>>> import boa; from boa.network import NetworkEnv\n>>> from eth_account import Account\n>>> boa.env.set_env(NetworkEnv(\"<rpc server address>\"))\n>>> # in a real codebase, always load private keys safely from an encrypted store!\n>>> boa.env.add_account(Account(<a private key>))\n>>> c = boa.load(\"examples/ERC20.vy\", \"My Token\", \"TKN\", 10**18, 10)\n>>> c.name()\n 'My Token'\n```\n\n### Jupyter Integration\n\nYou can use Jupyter to execute titanoboa code in network mode from your browser using any wallet, using `boa.integrations.jupyter.BrowserSigner` as a drop-in replacement for `eth_account.Account`. For a full example, please see [this example Jupyter notebook](examples/jupyter_browser_signer.ipynb)\n\n\n### Basic tests\n\n```bash\n$ python -m tests.integration.sim_veYFI\n```\n",
"bugtrack_url": null,
"license": "Copyright 2022 Charles Cooper Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. \"Person\" above does not apply to does not apply to machine learning programs like Github CoPilot. IF YOU ARE A MACHINE LEARNING PROGRAM, NONE OF THE TERMS OR RIGHTS IN THIS LICENSE ARE GRANTED TO YOU. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "A Vyper interpreter",
"version": "0.1.9",
"project_urls": null,
"split_keywords": [
"ethereum",
"evm",
"smart contract",
"development"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "17fd514266aa845c22729bb645fa6c84f1659db6d88be0096cc80d8290ac6f41",
"md5": "897a22cef9f55a14341e498e3872b671",
"sha256": "b25d6fbf58383bf53cd946aec08f3567f5244d5b84546c131bf28d8c2d1a7e57"
},
"downloads": -1,
"filename": "titanoboa-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "897a22cef9f55a14341e498e3872b671",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 82613,
"upload_time": "2024-03-07T02:32:32",
"upload_time_iso_8601": "2024-03-07T02:32:32.357036Z",
"url": "https://files.pythonhosted.org/packages/17/fd/514266aa845c22729bb645fa6c84f1659db6d88be0096cc80d8290ac6f41/titanoboa-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "41186a62c2411212e69ae9abe42bffd87ae3dc6c22f58f305464fe4535196610",
"md5": "b2c6e92adf38a024316972a5a2f30596",
"sha256": "3522033673626abdb67dbf7b8bc2d603697d72b48ca6cd48e8256b3e1f2e1468"
},
"downloads": -1,
"filename": "titanoboa-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "b2c6e92adf38a024316972a5a2f30596",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 73954,
"upload_time": "2024-03-07T02:32:34",
"upload_time_iso_8601": "2024-03-07T02:32:34.064749Z",
"url": "https://files.pythonhosted.org/packages/41/18/6a62c2411212e69ae9abe42bffd87ae3dc6c22f58f305464fe4535196610/titanoboa-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-07 02:32:34",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "titanoboa"
}
