fastweb3-objects 0.1.0__tar.gz

fastweb3_objects-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iamdefinitelyahuman
+
+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.
+
+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.

fastweb3_objects-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: fastweb3-objects
+Version: 0.1.0
+Summary: High-level objects built on fastweb3.
+Author: iamdefinitelyahuman
+License: MIT
+Project-URL: Homepage, https://github.com/iamdefinitelyahuman/fastweb3-objects
+Project-URL: Repository, https://github.com/iamdefinitelyahuman/fastweb3-objects
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: eth-stdlib<0.3,>=0.2.7
+Requires-Dist: fastweb3<0.2.0,>=0.1.6
+Requires-Dist: fastweb3-keypass<0.2.0,>=0.1.2
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pycryptodome>=3.20
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: pre-commit>=3; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: mkdocs>=1.6; extra == "dev"
+Requires-Dist: mkdocs-material>=9.5; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Dynamic: license-file
+
+# fastweb3-objects
+
+High-level EVM objects built on `fastweb3`.
+
+NOTE: This library is still in early alpha development. Prior to a `v1.0.0` (which may never come), expect breaking changes and no backward compatibility between versions.
+
+## Installation
+
+You can install the latest release via `pip`:
+
+    pip install fastweb3-objects
+
+Or clone the repository for the most up-to-date version:
+
+    git clone https://github.com/iamdefinitelyahuman/fastweb3-objects.git
+    cd fastweb3-objects
+    pip install -e .
+
+## Usage
+
+The main entry points are available directly from `fw3_objects`:
+
+    >>> from fw3_objects import Account, Accounts, Chain, Contract, Transaction
+
+### 1. Connect to a chain
+
+`Chain` is the canonical object for interacting with a specific EVM chain.
+
+    >>> chain = Chain(1)
+    >>> chain
+    Chain(1)
+
+The underlying `fastweb3.Web3` client is created lazily. By default, it uses `fastweb3`'s public RPC discovery and endpoint pooling.
+
+    >>> chain.height()
+    23100000
+
+You can access blocks by number, hash, tag, or index syntax:
+
+    >>> chain.get_block("latest")
+    {'number': 23100000, ...}
+
+    >>> chain[-1]
+    {'number': 23100000, ...}
+
+To use your own RPC endpoint, configure the chain before first use:
+
+    >>> from fw3_objects.chain import configure_chain
+
+    >>> configure_chain(1, endpoints=["http://localhost:8545"], use_public_pool=False)
+    >>> chain = Chain(1)
+
+### 2. Use a default chain context
+
+Objects can be bound explicitly to a chain, or they can use the active default chain.
+
+    >>> mainnet = Chain(1)
+
+    >>> with mainnet.as_default():
+    ...     vitalik = Account("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
+    ...     vitalik.balance()
+    ...
+    32131215082101779377
+
+Strict mode rejects accidental access through another chain while the context is active.
+
+    >>> with mainnet.as_default(strict=True):
+    ...     Account("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045").balance()
+
+### 3. Manage accounts
+
+`Accounts` is a `fastweb3-keypass` database wrapper. With no arguments, it opens the default database, creating it first if needed.
+
+    >>> accounts = Accounts()
+    Create password for new Accounts database 'default': ***
+
+    >>> accounts
+    <Accounts unlocked>
+
+Accounts created or imported through the database can sign transactions.
+
+    >>> acct = accounts.create_account(alias="deployer", set_as_default=True)
+    >>> acct
+    <Account 0x0D3AaC9458167352493864Af54D1CBD7F1B8fF68 signable>
+
+You can also create watch-only account objects directly from an address.
+
+    >>> vitalik = Account("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", chain=1)
+    >>> vitalik
+    <Account 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 watch-only>
+
+Chain-aware account helpers expose common RPC operations.
+
+    >>> vitalik.balance()
+    32131215082101779377
+
+    >>> vitalik.nonce()
+    1832
+
+    >>> vitalik.bytecode()
+    b''
+
+### 4. Send transactions
+
+Signing accounts can build, sign, broadcast, and watch transactions in a single call.
+
+    >>> tx = acct.transact(
+    ...     to="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+    ...     value=10**18,
+    ...     chain=1,
+    ... )
+
+The returned `Transaction` object tracks mempool, receipt, replacement, and revert state.
+
+    >>> tx.status
+    <TxStatus.PENDING: -1>
+
+    >>> tx.wait()
+    >>> tx.status
+    <TxStatus.CONFIRMED: 1>
+
+    >>> tx.block_number
+    23100012
+
+    >>> tx.gas_used
+    21000
+
+Pending transactions can be replaced with a higher-fee transaction when the sender is available in an open `Accounts` database.
+
+    >>> replacement = tx.replace()
+
+### 5. Interact with contracts
+
+`Contract` binds an address, ABI, and chain. ABI can be provided directly, loaded from a JSON file, loaded from cache, or fetched from a supported block explorer.
+
+    >>> usdc = Contract("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", chain=1)
+
+Function ABIs are installed as callable attributes.
+
+    >>> usdc.name()
+    'USD Coin'
+
+    >>> usdc.symbol()
+    'USDC'
+
+    >>> usdc.balanceOf("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
+    123456789
+
+Read-only functions perform `eth_call`. Nonpayable and payable functions build, sign, broadcast, and return a `Transaction`.
+
+    >>> tx = usdc.transfer(
+    ...     "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+    ...     1_000_000,
+    ...     sender=acct,
+    ... )
+
+    >>> tx.wait()
+
+Contract methods also expose encoding and decoding helpers.
+
+    >>> calldata = usdc.transfer.encode_input(
+    ...     "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+    ...     1_000_000,
+    ... )
+
+    >>> usdc.transfer.decode_input(calldata)
+    ('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', 1000000)
+
+### 6. Inspect transactions
+
+A transaction hash can be wrapped directly.
+
+    >>> tx = Transaction("0xf3063ed07203bc337636f1aa8cb521aa819478df764100950eebea00760a296c", chain=1)
+
+Transaction properties wait for the first monitor update before returning.
+
+    >>> tx.sender
+    <Account 0x0D3AaC9458167352493864Af54D1CBD7F1B8fF68 watch-only>
+
+    >>> tx.receiver
+    <Account 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 watch-only>
+
+    >>> tx.value
+    1000000000000000000
+
+Decoded receipt events are available lazily from `tx.events`.
+
+    >>> len(tx.events)
+    1
+
+## Tests
+
+First, install the dev dependencies:
+
+    pip install -e ".[dev]"
+
+To run the test suite:
+
+    pytest
+
+## License
+
+This project is licensed under the MIT license.

fastweb3_objects-0.1.0/README.md

@@ -0,0 +1,203 @@
+# fastweb3-objects
+
+High-level EVM objects built on `fastweb3`.
+
+NOTE: This library is still in early alpha development. Prior to a `v1.0.0` (which may never come), expect breaking changes and no backward compatibility between versions.
+
+## Installation
+
+You can install the latest release via `pip`:
+
+    pip install fastweb3-objects
+
+Or clone the repository for the most up-to-date version:
+
+    git clone https://github.com/iamdefinitelyahuman/fastweb3-objects.git
+    cd fastweb3-objects
+    pip install -e .
+
+## Usage
+
+The main entry points are available directly from `fw3_objects`:
+
+    >>> from fw3_objects import Account, Accounts, Chain, Contract, Transaction
+
+### 1. Connect to a chain
+
+`Chain` is the canonical object for interacting with a specific EVM chain.
+
+    >>> chain = Chain(1)
+    >>> chain
+    Chain(1)
+
+The underlying `fastweb3.Web3` client is created lazily. By default, it uses `fastweb3`'s public RPC discovery and endpoint pooling.
+
+    >>> chain.height()
+    23100000
+
+You can access blocks by number, hash, tag, or index syntax:
+
+    >>> chain.get_block("latest")
+    {'number': 23100000, ...}
+
+    >>> chain[-1]
+    {'number': 23100000, ...}
+
+To use your own RPC endpoint, configure the chain before first use:
+
+    >>> from fw3_objects.chain import configure_chain
+
+    >>> configure_chain(1, endpoints=["http://localhost:8545"], use_public_pool=False)
+    >>> chain = Chain(1)
+
+### 2. Use a default chain context
+
+Objects can be bound explicitly to a chain, or they can use the active default chain.
+
+    >>> mainnet = Chain(1)
+
+    >>> with mainnet.as_default():
+    ...     vitalik = Account("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
+    ...     vitalik.balance()
+    ...
+    32131215082101779377
+
+Strict mode rejects accidental access through another chain while the context is active.
+
+    >>> with mainnet.as_default(strict=True):
+    ...     Account("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045").balance()
+
+### 3. Manage accounts
+
+`Accounts` is a `fastweb3-keypass` database wrapper. With no arguments, it opens the default database, creating it first if needed.
+
+    >>> accounts = Accounts()
+    Create password for new Accounts database 'default': ***
+
+    >>> accounts
+    <Accounts unlocked>
+
+Accounts created or imported through the database can sign transactions.
+
+    >>> acct = accounts.create_account(alias="deployer", set_as_default=True)
+    >>> acct
+    <Account 0x0D3AaC9458167352493864Af54D1CBD7F1B8fF68 signable>
+
+You can also create watch-only account objects directly from an address.
+
+    >>> vitalik = Account("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", chain=1)
+    >>> vitalik
+    <Account 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 watch-only>
+
+Chain-aware account helpers expose common RPC operations.
+
+    >>> vitalik.balance()
+    32131215082101779377
+
+    >>> vitalik.nonce()
+    1832
+
+    >>> vitalik.bytecode()
+    b''
+
+### 4. Send transactions
+
+Signing accounts can build, sign, broadcast, and watch transactions in a single call.
+
+    >>> tx = acct.transact(
+    ...     to="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+    ...     value=10**18,
+    ...     chain=1,
+    ... )
+
+The returned `Transaction` object tracks mempool, receipt, replacement, and revert state.
+
+    >>> tx.status
+    <TxStatus.PENDING: -1>
+
+    >>> tx.wait()
+    >>> tx.status
+    <TxStatus.CONFIRMED: 1>
+
+    >>> tx.block_number
+    23100012
+
+    >>> tx.gas_used
+    21000
+
+Pending transactions can be replaced with a higher-fee transaction when the sender is available in an open `Accounts` database.
+
+    >>> replacement = tx.replace()
+
+### 5. Interact with contracts
+
+`Contract` binds an address, ABI, and chain. ABI can be provided directly, loaded from a JSON file, loaded from cache, or fetched from a supported block explorer.
+
+    >>> usdc = Contract("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", chain=1)
+
+Function ABIs are installed as callable attributes.
+
+    >>> usdc.name()
+    'USD Coin'
+
+    >>> usdc.symbol()
+    'USDC'
+
+    >>> usdc.balanceOf("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
+    123456789
+
+Read-only functions perform `eth_call`. Nonpayable and payable functions build, sign, broadcast, and return a `Transaction`.
+
+    >>> tx = usdc.transfer(
+    ...     "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+    ...     1_000_000,
+    ...     sender=acct,
+    ... )
+
+    >>> tx.wait()
+
+Contract methods also expose encoding and decoding helpers.
+
+    >>> calldata = usdc.transfer.encode_input(
+    ...     "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+    ...     1_000_000,
+    ... )
+
+    >>> usdc.transfer.decode_input(calldata)
+    ('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', 1000000)
+
+### 6. Inspect transactions
+
+A transaction hash can be wrapped directly.
+
+    >>> tx = Transaction("0xf3063ed07203bc337636f1aa8cb521aa819478df764100950eebea00760a296c", chain=1)
+
+Transaction properties wait for the first monitor update before returning.
+
+    >>> tx.sender
+    <Account 0x0D3AaC9458167352493864Af54D1CBD7F1B8fF68 watch-only>
+
+    >>> tx.receiver
+    <Account 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 watch-only>
+
+    >>> tx.value
+    1000000000000000000
+
+Decoded receipt events are available lazily from `tx.events`.
+
+    >>> len(tx.events)
+    1
+
+## Tests
+
+First, install the dev dependencies:
+
+    pip install -e ".[dev]"
+
+To run the test suite:
+
+    pytest
+
+## License
+
+This project is licensed under the MIT license.

fastweb3_objects-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fastweb3-objects"
+version = "0.1.0"
+description = "High-level objects built on fastweb3."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [
+    { name = "iamdefinitelyahuman" }
+]
+
+dependencies = [
+    "eth-stdlib>=0.2.7,<0.3",
+    "fastweb3>=0.1.6,<0.2.0",
+    "fastweb3-keypass>=0.1.2,<0.2.0",
+    "platformdirs>=4.0",
+    "pycryptodome>=3.20",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.9",
+    "pre-commit>=3",
+    "build",
+    "twine",
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/iamdefinitelyahuman/fastweb3-objects"
+Repository = "https://github.com/iamdefinitelyahuman/fastweb3-objects"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.pytest.ini_options]
+addopts = [
+  "--cov=fw3_objects",
+  "--cov-report=term-missing",
+  "--cov-report=xml",
+]
+testpaths = ["tests"]

fastweb3_objects-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+