propamm 1.0.0__tar.gz

propamm-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/

propamm-1.0.0/LICENSE

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

propamm-1.0.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: propamm
+Version: 1.0.0
+Summary: Python SDK for interacting with the PropAMM contracts
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: certifi
+Requires-Dist: eth-abi>=5
+Requires-Dist: eth-account>=0.11
+Requires-Dist: eth-utils>=4
+Requires-Dist: web3<8,>=7
+Requires-Dist: websockets>=12
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PropAMM Python SDK
+
+An async Python SDK for the `PropAMMRouter` contract, built on
+[web3.py](https://web3py.readthedocs.io/). 
+Features:
+- **Typed router bindings**: quote and swap across all whitelisted venues, a
+  single venue, or a chosen subset, plus the router's views and ERC-20 approvals.
+- **Accurate quotes**: quotes automatically apply fresh pAMM state overrides,
+  so they price live off-chain liquidity rather than stale on-chain state.
+- **Helpers**: amount/unit conversion, slippage, deadlines, and well-known
+  token and venue addresses.
+- **A typed error hierarchy**: contract reverts surface as human-readable
+  errors (e.g. `InsufficientOutput(...)`).
+
+Method names drop the on-chain `V1` suffix (`router.swap(...)` calls `swapV1`).
+A client is read-only by default; pass an account to send transactions.
+
+## Setup
+
+Using [uv](https://docs.astral.sh/uv/) (installs the exact pinned versions from `uv.lock`):
+
+```sh
+uv sync --extra dev
+uv run pytest          # incl. ABI selector & overrides regression tests
+uv run ruff check .
+```
+
+Using pip (resolves the dependency ranges in `pyproject.toml`):
+
+```sh
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## Getting started
+
+Quote and swap 1 ETH for USDC through the best venue:
+
+```python
+import asyncio
+from propamm import ContractClient, PropAmmRouter, SwapParams
+from propamm.common.accounts import account_from_key
+from propamm.common.helpers import apply_slippage, deadline_in, parse_ether
+from propamm.common.tokens import ETH_SENTINEL, USDC
+
+PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80" # anvil rich account
+RPC_URL = "http://localhost:8545" # local anvil instance
+ROUTER_ADDRESS = "0x4DdF368080CD7946db5b459aD591c350158175e1" # mainnet router deployment
+
+async def main():
+    account = account_from_key(PRIVATE_KEY)
+    client = ContractClient(RPC_URL, account=account)
+    router = PropAmmRouter(client, ROUTER_ADDRESS)
+
+    amount_in = parse_ether("1")
+    quote = await router.quote(ETH_SENTINEL, USDC, amount_in)
+
+    result = await router.swap_and_wait(
+        SwapParams(
+            token_in=ETH_SENTINEL,
+            token_out=USDC,
+            amount_in=amount_in,
+            amount_out_min=apply_slippage(quote.amount_out, 50),  # quote - 0.5%
+            recipient=account.address,
+            deadline=deadline_in(300),  # now + 5 min
+        )
+    )
+    print(f"received {result.amount_out} USDC via {result.executed_venue}")
+
+
+asyncio.run(main())
+```
+
+A runnable version lives in [`examples/getting_started.py`](examples/getting_started.py).
+
+```sh
+python3 examples/getting_started.py
+```
+
+It defaults to a local anvil mainnet fork (`anvil --fork-url <mainnet rpc>`)
+with anvil's default funded account and the mainnet router deployment. Override
+with `RPC_URL` / `PRIVATE_KEY` / `ROUTER_ADDRESS` / `SLIPPAGE_BPS`.
+
+## Layout
+
+| Module | Purpose |
+| --- | --- |
+| `propamm.client` | `ContractClient`: `AsyncWeb3` wrapper (`contract` / `call_with_overrides` / `send` / `wait_for_transaction`). |
+| `propamm.router` | `PropAmmRouter` bindings: quotes, swaps, ERC-20, views. |
+| `propamm.router.abi` | Vendored router ABI and custom-error naming. |
+| `propamm.overrides` | pAMM state-override sources (`OverridesRpcSource`, `OverridesWsSource`). |
+| `propamm.common` | `tokens`, `pamms`, `helpers`, `accounts`. |
+
+## Quotes & state overrides
+
+Quote functions are nonpayable on-chain (not `view`), so they run through
+`eth_call` simulation. By default each quote attaches the latest pAMM state
+overrides (streamed from Titan via `OverridesWsSource`) plus the snapshot's
+block number/timestamp, so venues price fresh off-chain liquidity. Pass
+`QuoteOptions(overrides=None)` to quote without overrides, or supply your own
+`OverridesSource` / `OverridesSnapshot`.
+
+> Note: quotes apply fresh overrides, but a fork still *executes* swaps against
+> its frozen state — if a swap reverts with `InsufficientOutput` on a fork,
+> raise the slippage. Live chains fill at the quoted state normally.

propamm-1.0.0/README.md

@@ -0,0 +1,107 @@
+# PropAMM Python SDK
+
+An async Python SDK for the `PropAMMRouter` contract, built on
+[web3.py](https://web3py.readthedocs.io/). 
+Features:
+- **Typed router bindings**: quote and swap across all whitelisted venues, a
+  single venue, or a chosen subset, plus the router's views and ERC-20 approvals.
+- **Accurate quotes**: quotes automatically apply fresh pAMM state overrides,
+  so they price live off-chain liquidity rather than stale on-chain state.
+- **Helpers**: amount/unit conversion, slippage, deadlines, and well-known
+  token and venue addresses.
+- **A typed error hierarchy**: contract reverts surface as human-readable
+  errors (e.g. `InsufficientOutput(...)`).
+
+Method names drop the on-chain `V1` suffix (`router.swap(...)` calls `swapV1`).
+A client is read-only by default; pass an account to send transactions.
+
+## Setup
+
+Using [uv](https://docs.astral.sh/uv/) (installs the exact pinned versions from `uv.lock`):
+
+```sh
+uv sync --extra dev
+uv run pytest          # incl. ABI selector & overrides regression tests
+uv run ruff check .
+```
+
+Using pip (resolves the dependency ranges in `pyproject.toml`):
+
+```sh
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## Getting started
+
+Quote and swap 1 ETH for USDC through the best venue:
+
+```python
+import asyncio
+from propamm import ContractClient, PropAmmRouter, SwapParams
+from propamm.common.accounts import account_from_key
+from propamm.common.helpers import apply_slippage, deadline_in, parse_ether
+from propamm.common.tokens import ETH_SENTINEL, USDC
+
+PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80" # anvil rich account
+RPC_URL = "http://localhost:8545" # local anvil instance
+ROUTER_ADDRESS = "0x4DdF368080CD7946db5b459aD591c350158175e1" # mainnet router deployment
+
+async def main():
+    account = account_from_key(PRIVATE_KEY)
+    client = ContractClient(RPC_URL, account=account)
+    router = PropAmmRouter(client, ROUTER_ADDRESS)
+
+    amount_in = parse_ether("1")
+    quote = await router.quote(ETH_SENTINEL, USDC, amount_in)
+
+    result = await router.swap_and_wait(
+        SwapParams(
+            token_in=ETH_SENTINEL,
+            token_out=USDC,
+            amount_in=amount_in,
+            amount_out_min=apply_slippage(quote.amount_out, 50),  # quote - 0.5%
+            recipient=account.address,
+            deadline=deadline_in(300),  # now + 5 min
+        )
+    )
+    print(f"received {result.amount_out} USDC via {result.executed_venue}")
+
+
+asyncio.run(main())
+```
+
+A runnable version lives in [`examples/getting_started.py`](examples/getting_started.py).
+
+```sh
+python3 examples/getting_started.py
+```
+
+It defaults to a local anvil mainnet fork (`anvil --fork-url <mainnet rpc>`)
+with anvil's default funded account and the mainnet router deployment. Override
+with `RPC_URL` / `PRIVATE_KEY` / `ROUTER_ADDRESS` / `SLIPPAGE_BPS`.
+
+## Layout
+
+| Module | Purpose |
+| --- | --- |
+| `propamm.client` | `ContractClient`: `AsyncWeb3` wrapper (`contract` / `call_with_overrides` / `send` / `wait_for_transaction`). |
+| `propamm.router` | `PropAmmRouter` bindings: quotes, swaps, ERC-20, views. |
+| `propamm.router.abi` | Vendored router ABI and custom-error naming. |
+| `propamm.overrides` | pAMM state-override sources (`OverridesRpcSource`, `OverridesWsSource`). |
+| `propamm.common` | `tokens`, `pamms`, `helpers`, `accounts`. |
+
+## Quotes & state overrides
+
+Quote functions are nonpayable on-chain (not `view`), so they run through
+`eth_call` simulation. By default each quote attaches the latest pAMM state
+overrides (streamed from Titan via `OverridesWsSource`) plus the snapshot's
+block number/timestamp, so venues price fresh off-chain liquidity. Pass
+`QuoteOptions(overrides=None)` to quote without overrides, or supply your own
+`OverridesSource` / `OverridesSnapshot`.
+
+> Note: quotes apply fresh overrides, but a fork still *executes* swaps against
+> its frozen state — if a swap reverts with `InsufficientOutput` on a fork,
+> raise the slippage. Live chains fill at the quoted state normally.

propamm-1.0.0/examples/getting_started.py

@@ -0,0 +1,77 @@
+"""Getting started: quote and swap 1 ETH for USDC through the best venue.
+
+Install the SDK first, then run:
+
+    pip install -e .
+    python3 examples/getting_started.py
+
+Defaults target a local anvil mainnet fork (`anvil --fork-url <mainnet rpc>`)
+with anvil's default funded account and the mainnet router deployment.
+Override with RPC_URL / PRIVATE_KEY / ROUTER_ADDRESS / SLIPPAGE_BPS.
+
+Note: quotes automatically apply fresh pAMM state overrides (streamed from
+Titan), but a fork still *executes* swaps against its frozen state — if the
+swap reverts with `InsufficientOutput` there, raise SLIPPAGE_BPS (live chains
+fill at the quoted state normally).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from propamm import ContractClient, PropAmmRouter, SwapParams
+from propamm.common.accounts import account_from_key
+from propamm.common.helpers import (
+    apply_slippage,
+    deadline_in,
+    format_ether,
+    format_units,
+    parse_ether,
+)
+from propamm.common.tokens import ETH_SENTINEL, USDC
+
+USDC_DECIMALS = 6
+
+RPC_URL = os.getenv("RPC_URL", "http://localhost:8545")
+# anvil's default funded account #0
+PRIVATE_KEY = os.getenv(
+    "PRIVATE_KEY", "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+)
+# mainnet router deployment
+ROUTER_ADDRESS = os.getenv("ROUTER_ADDRESS", "0x4DdF368080CD7946db5b459aD591c350158175e1")
+SLIPPAGE_BPS = int(os.getenv("SLIPPAGE_BPS", "50"))
+
+
+async def main() -> None:
+    account = account_from_key(PRIVATE_KEY)
+    client = ContractClient(RPC_URL, account=account)
+    router = PropAmmRouter(client, ROUTER_ADDRESS)
+
+    amount_in = parse_ether("1")
+    quote = await router.quote(ETH_SENTINEL, USDC, amount_in)
+    print(
+        f"quote: {format_ether(amount_in)} ETH -> "
+        f"{format_units(quote.amount_out, USDC_DECIMALS)} USDC via {quote.venue}"
+    )
+
+    result = await router.swap_and_wait(
+        SwapParams(
+            token_in=ETH_SENTINEL,
+            token_out=USDC,
+            amount_in=amount_in,
+            amount_out_min=apply_slippage(quote.amount_out, SLIPPAGE_BPS),
+            recipient=account.address,
+            deadline=deadline_in(300),  # now + 5 min
+        )
+    )
+    print(
+        f"swapped: received {format_units(result.amount_out, USDC_DECIMALS)} USDC "
+        f"via {result.executed_venue} (tx {result.hash})"
+    )
+
+    await router.overrides.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

propamm-1.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "propamm"
+version = "1.0.0"
+description = "Python SDK for interacting with the PropAMM contracts"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "web3>=7,<8",
+    "eth-abi>=5",
+    "eth-utils>=4",
+    "eth-account>=0.11",
+    "aiohttp>=3.9",
+    "websockets>=12",
+    "certifi",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/propamm"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "examples", "tests"]

propamm-1.0.0/src/propamm/__init__.py

@@ -0,0 +1,62 @@
+"""Python SDK for interacting with the PropAMM contracts over JSON-RPC.
+
+Provides a generic :class:`ContractClient`, typed :class:`PropAmmRouter`
+bindings (quotes, swaps, and views), and pAMM state-override sources so quotes
+price fresh off-chain liquidity.
+"""
+
+from __future__ import annotations
+
+from .client import ContractClient
+from .error import (
+    ClientError,
+    InvalidInputError,
+    MissingEventError,
+    OverridesError,
+    PropAmmError,
+    RevertError,
+    TimeoutError,
+    TransactionRevertedError,
+)
+from .overrides import (
+    OverridesRpcSource,
+    OverridesSnapshot,
+    OverridesSource,
+    OverridesWsSource,
+)
+from .router import (
+    MAX_FEE_BPS,
+    FeeCharged,
+    FrontendFee,
+    PropAmmRouter,
+    Quote,
+    QuoteOptions,
+    SwapOptions,
+    SwapParams,
+    SwapResult,
+)
+
+__all__ = [
+    "MAX_FEE_BPS",
+    "ClientError",
+    "ContractClient",
+    "FeeCharged",
+    "FrontendFee",
+    "InvalidInputError",
+    "MissingEventError",
+    "OverridesError",
+    "OverridesRpcSource",
+    "OverridesSnapshot",
+    "OverridesSource",
+    "OverridesWsSource",
+    "PropAmmError",
+    "PropAmmRouter",
+    "Quote",
+    "QuoteOptions",
+    "RevertError",
+    "SwapOptions",
+    "SwapParams",
+    "SwapResult",
+    "TimeoutError",
+    "TransactionRevertedError",
+]

propamm-1.0.0/src/propamm/_tls.py

@@ -0,0 +1,19 @@
+"""Shared TLS context backed by certifi's CA bundle.
+
+The system cert store is empty on some Python builds (e.g. python.org installers
+on macOS), which makes every TLS verification fail. Using certifi's bundled
+Mozilla roots avoids depending on how Python was installed.
+"""
+
+from __future__ import annotations
+
+import ssl
+from functools import lru_cache
+
+import certifi
+
+
+@lru_cache(maxsize=1)
+def ssl_context() -> ssl.SSLContext:
+    """A default TLS context that verifies against certifi's CA bundle."""
+    return ssl.create_default_context(cafile=certifi.where())

propamm-1.0.0/src/propamm/client.py

@@ -0,0 +1,180 @@
+"""Thin wrapper around ``AsyncWeb3`` for reading from and writing to contracts.
+
+web3.py does the heavy lifting — contract calls, ABI encode/decode, event
+decoding, transaction building/signing. The one thing it doesn't expose is
+``eth_call`` with a *block* override (the 4th RPC parameter), which on-chain
+quotes need so venues see a matching block context; :meth:`call_with_overrides`
+fills that gap with a raw request and re-shapes reverts into :class:`RevertError`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from eth_account.signers.local import LocalAccount
+from eth_typing import ChecksumAddress
+from eth_utils import to_checksum_address
+from web3 import AsyncWeb3
+from web3.contract import AsyncContract
+from web3.contract.async_contract import AsyncContractFunction
+from web3.exceptions import ContractLogicError, Web3Exception
+
+from ._tls import ssl_context
+from .common.accounts import account_from_key
+from .error import ClientError, RevertError
+
+#: How long ``wait_for_transaction`` polls before giving up, in seconds.
+RECEIPT_TIMEOUT_SECONDS = 120
+
+
+class ContractClient:
+    """JSON-RPC contract client.
+
+    Construct read-only with ``ContractClient(rpc_url)`` (quotes and views
+    work; sends don't) or signing with ``ContractClient(rpc_url, account=...)``
+    / :meth:`connect_with_signer`.
+    """
+
+    def __init__(self, rpc_url: str, account: LocalAccount | None = None) -> None:
+        # Verify TLS against certifi's CA bundle rather than the (sometimes empty)
+        # system store, so an https RPC works regardless of how Python was installed.
+        request_kwargs = {"ssl": ssl_context()} if rpc_url.startswith("https") else {}
+        self.w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(rpc_url, request_kwargs=request_kwargs))
+        self.account = account
+
+    @classmethod
+    def connect(cls, rpc_url: str) -> ContractClient:
+        """Read-only client."""
+        return cls(rpc_url)
+
+    @classmethod
+    def connect_with_signer(cls, rpc_url: str, private_key: str) -> ContractClient:
+        """Signing client from a 0x-prefixed (or bare) private key."""
+        return cls(rpc_url, account_from_key(private_key))
+
+    @property
+    def signer_address(self) -> ChecksumAddress | None:
+        """Address of the configured signer, if any."""
+        return self.account.address if self.account else None
+
+    def contract(self, address: str, abi: list) -> AsyncContract:
+        """A web3 contract bound to ``address`` and ``abi``."""
+        return self.w3.eth.contract(address=to_checksum_address(address), abi=abi)
+
+    async def call_with_overrides(
+        self,
+        function: AsyncContractFunction,
+        *,
+        state_override: dict[str, Any] | None = None,
+        block_number: int | None = None,
+        block_timestamp: int | None = None,
+    ) -> bytes:
+        """``eth_call`` a function with state and/or block overrides; return raw data.
+
+        web3's ``ContractFunction.call`` supports state overrides but not block
+        overrides, so this issues the raw request. The caller decodes the
+        result with the function's ABI.
+        """
+        tx: dict[str, Any] = {
+            "to": function.address,
+            "data": function._encode_transaction_data(),
+        }
+        if self.signer_address is not None:
+            tx["from"] = self.signer_address
+
+        params: list[Any] = [tx, "latest"]
+        block_overrides: dict[str, str] = {}
+        if block_number is not None:
+            block_overrides["number"] = hex(block_number)
+        if block_timestamp is not None:
+            block_overrides["time"] = hex(block_timestamp)
+        if block_overrides:
+            params.extend([state_override or {}, block_overrides])
+        elif state_override:
+            params.append(state_override)
+
+        response = await self.w3.provider.make_request("eth_call", params)
+        if response.get("error"):
+            raise _revert_from_rpc_error(response["error"])
+        result = response.get("result")
+        if result is None:
+            raise ClientError("eth_call returned no result")
+        return bytes(self.w3.to_bytes(hexstr=result))
+
+    async def send(self, function: AsyncContractFunction, value: int | None = None) -> str:
+        """Build, sign, and send ``function`` as a transaction. Returns the tx hash.
+
+        web3 fills nonce, gas, fees, and chain id via ``build_transaction``.
+        """
+        if self.account is None:
+            raise ClientError("ContractClient was created without a signer; sends are unavailable")
+        try:
+            # web3 fills gas, fees, and chain id in `build_transaction`, but not the
+            # nonce — supply it ourselves (pending, so back-to-back sends don't collide).
+            nonce = await self.w3.eth.get_transaction_count(self.account.address, "pending")
+            tx = await function.build_transaction(
+                {"from": self.account.address, "value": value or 0, "nonce": nonce}
+            )
+            signed = self.account.sign_transaction(tx)
+            raw = getattr(signed, "raw_transaction", None) or signed.rawTransaction
+            return self.w3.to_hex(await self.w3.eth.send_raw_transaction(raw))
+        except ContractLogicError as exc:
+            # A revert surfaced during gas estimation (e.g. slippage, deadline).
+            # web3 has no ABI context here, so it carries only the raw revert
+            # payload — pass it through on `data` so the router can name it.
+            raise RevertError(_web3_message(exc), _revert_data(exc)) from exc
+        except Web3Exception as exc:
+            # Insufficient funds, bad nonce, transport failure, ... — keep the
+            # SDK's exception surface consistent (see ClientError's docstring).
+            raise ClientError(_web3_message(exc)) from exc
+
+    async def wait_for_transaction(self, tx_hash: str) -> Any:
+        """Wait until a transaction is mined and return its receipt."""
+        return await self.w3.eth.wait_for_transaction_receipt(
+            tx_hash, timeout=RECEIPT_TIMEOUT_SECONDS
+        )
+
+
+def _revert_data(exc: ContractLogicError) -> bytes | None:
+    """The raw revert payload off a web3 contract error, as bytes (or ``None``)."""
+    raw = getattr(exc, "data", None)
+    if isinstance(raw, (bytes, bytearray)):
+        return bytes(raw)
+    if isinstance(raw, str) and raw.startswith("0x") and len(raw) > 2:
+        try:
+            return bytes.fromhex(raw[2:])
+        except ValueError:
+            return None
+    return None
+
+
+def _web3_message(exc: Web3Exception) -> str:
+    """Extract a clean message from a web3 exception.
+
+    web3 stores ``(message, data)`` in ``args`` (so ``str(exc)`` is an ugly
+    tuple), and ``Web3RPCError.message`` is the raw JSON-RPC error object —
+    prefer ``.message``, unwrapping the nested ``message`` when it's a dict.
+    """
+    message = getattr(exc, "message", None)
+    if isinstance(message, dict):
+        return message.get("message") or str(message)
+    return message or str(exc)
+
+
+def _revert_from_rpc_error(error: dict[str, Any]) -> RevertError:
+    """Re-shape a JSON-RPC ``error`` object into a :class:`RevertError`.
+
+    The revert payload arrives in ``error.data`` (a hex string, sometimes
+    nested) on reverts; recover it so the router can name the custom error.
+    """
+    message = error.get("message", "execution reverted")
+    raw = error.get("data")
+    if isinstance(raw, dict):
+        raw = raw.get("data") or raw.get("result")
+    data: bytes | None = None
+    if isinstance(raw, str) and raw.startswith("0x") and len(raw) > 2:
+        try:
+            data = bytes.fromhex(raw[2:])
+        except ValueError:
+            data = None
+    return RevertError(message, data)

propamm-1.0.0/src/propamm/common/__init__.py

@@ -0,0 +1 @@
+"""Shared constants and conversion helpers (tokens, pAMMs, units, accounts)."""

propamm-1.0.0/src/propamm/common/accounts.py

@@ -0,0 +1,17 @@
+"""Thin wrappers around ``eth_account`` for building signing accounts."""
+
+from __future__ import annotations
+
+from eth_account import Account
+from eth_account.signers.local import LocalAccount
+
+
+def account_from_key(private_key: str) -> LocalAccount:
+    """Build a local signing account from a 0x-prefixed (or bare) private key."""
+    return Account.from_key(private_key)
+
+
+def account_from_mnemonic(mnemonic: str, account_path: str = "m/44'/60'/0'/0/0") -> LocalAccount:
+    """Build a local signing account from a BIP-39 mnemonic."""
+    Account.enable_unaudited_hdwallet_features()
+    return Account.from_mnemonic(mnemonic, account_path=account_path)