aether-chain-client 0.2.9__tar.gz

aether_chain_client-0.2.9/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: aether-chain-client
+Version: 0.2.9
+Summary: Python client for the Aether chain: ML-DSA-44 keys, payments, buying and selling paid APIs (x402 aether-memo / aether-prepaid) and the service directory.
+License: MIT
+Project-URL: Homepage, https://github.com/whoyoujoshin/aether/tree/main/clients/python#readme
+Project-URL: Repository, https://github.com/whoyoujoshin/aether
+Project-URL: Issues, https://github.com/whoyoujoshin/aether/issues
+Keywords: aether,ai-agents,agent-payments,x402,mcp,blockchain,cosmos,post-quantum,ml-dsa,usdc
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: dilithium-py<2,>=1.4
+Requires-Dist: mnemonic>=0.21
+
+# aether-chain-client
+
+Python client for the [Aether](https://github.com/whoyoujoshin/aether) chain: ML-DSA-44 keys, sending and receiving AETH, buying from and selling paid APIs (x402 `aether-memo`, `aether-prepaid` and `aether-pull`) and the on-chain service directory. It talks to a node's CometBFT RPC (port 26657) only.
+
+```python
+import os
+from aether_client import AetherClient, Key, fetch_paid, find_services, rate_service, withdraw_prepaid
+
+client = AetherClient("http://localhost:26657", "aether-testnet-1")
+key = Key.from_mnemonic(os.environ["AETHER_MNEMONIC"])  # same address as `aetherd keys add` / `agentmcp`
+
+sent = client.send(key, "aether1...", "0.5 AETH", memo="invoice-42")
+done = client.wait_for_transaction(sent.hash)            # confirmed | failed | pending (timeout)
+# Retrying after an error: client.rebroadcast(sent.signed) -- never a second send().
+
+res = fetch_paid(client, key, "https://api.example.com/forecast", max_amount="0.05 AETH", prepay="1 AETH")
+# Or, where offered, pay from your own account under a capped, 7-day allowance the seller collects from later:
+res2 = fetch_paid(client, key, "https://api.example.com/forecast", max_amount="0.05 AETH", pull_allowance="1 AETH")
+services = find_services(client, query="weather", max_price="0.1 AETH", trusted=[owner_address])
+# services[i].reputation: payments, payers, ratings (can be faked), trusted_ratings (can't)
+# res.receipt: the seller's signed receipt and whether it matches exactly what was sent and received
+rate_service(client, key, "https://api.example.com", 5)  # only raters who paid a service count
+back = withdraw_prepaid(client, key, "https://api.example.com", withdrawal_id="w1")  # unspent prepaid balance
+```
+
+## Selling
+
+Charge per request from a Python service -- all three payment schemes, the `/.well-known/x402` manifest for the service directory, and withdrawals of unspent prepaid balances. Compatible with the Go paywall and every Aether buyer.
+
+```python
+import os
+from fastapi import FastAPI, Request
+from aether_client import AetherClient, Key, Paywall
+
+client = AetherClient("http://localhost:26657", "aether-testnet-1")
+pw = Paywall(client, "aether1...", "0.01 AETH", name="Weather", description="Forecasts by city",
+             prepaid_ledger="ledger.json",           # customers' balances: back it up
+             min_deposit="0.1 AETH",
+             payout_key=Key.from_mnemonic(os.environ["PAYOUT_MNEMONIC"]),  # pays withdrawals; keep a small float in it
+             receipt_key=payee_key,  # sign a receipt for every paid response (or a delegated key + receipt_delegation)
+             pull_collector_key=Key.from_mnemonic(os.environ["COLLECTOR_MNEMONIC"]), pull_credit="1 AETH")  # aether-pull: needs no funds
+pw.start_collecting()  # collects what aether-pull buyers owe, in batches
+api = FastAPI()
+
+@api.get("/forecast")
+async def forecast(request: Request):
+    return {"paid_by": request.scope["aether"].payer}
+
+app = pw.asgi(api, free=["/health"])   # Flask/Django: app.wsgi_app = pw.wsgi(app.wsgi_app); who paid: environ["aether.payment"]
+```
+
+The ledger is one JSON file (the Go paywall's format) for one process. Chain lookups block, so the ASGI adapter runs them in a thread.
+
+Amounts always carry a unit (`"1.5 AETH"`, `"1500000uaeth"`).
+
+**USDC.** `AetherClient(rpc, chain_id, usdc_channel="channel-N")` (Aether's end of its channel to Noble) also knows USDC: Noble's `uusdc` over exactly that channel, never a lookalike that arrived another way. For USDC that arrives another route, give its denom trace and its denom on the issuing chain instead: `usdc_path="transfer/channel-2", usdc_base_denom="erc20:0x0C382e685bbeeFE5d3d9C29e29E341fEE8E84C5d", usdc_issuer="Injective"` (`usdc_base_denom` defaults to `uusdc`). Then `send(key, to, "5 USDC")` sends USDC, `balances(address)` lists each asset, `wait_for_payment` matches in the asset of `min_amount`, and `fetch_paid` pays services priced in USDC with `max_amount` (and `prepay` / `pull_allowance`) in USDC; an amount in another asset than the service charges is refused with `ASSET_MISMATCH` before anything is paid. Results carry `asset`, `amount`, `balance`, `owed` and `allowance` in that asset's base units; the `*_uaeth` fields are set only for AETH. Without the channel, `"5 USDC"` is an unknown unit. The seller kit charges USDC too: `Paywall(client, pay_to, "0.05 USDC", usdc_channel="channel-N")` charges Noble USDC for everything (payments, deposits and balances, pull allowances and collections, withdrawals), `min_deposit` and `pull_credit` must then be in USDC, and 402s, the manifest and receipts carry the asset exactly as `cmd/paywall`'s do.
+
+Tests: `python -m unittest discover -s tests` (checked against `../testdata/vectors.json`, generated by the Go code).

aether_chain_client-0.2.9/README.md

@@ -0,0 +1,58 @@
+# aether-chain-client
+
+Python client for the [Aether](https://github.com/whoyoujoshin/aether) chain: ML-DSA-44 keys, sending and receiving AETH, buying from and selling paid APIs (x402 `aether-memo`, `aether-prepaid` and `aether-pull`) and the on-chain service directory. It talks to a node's CometBFT RPC (port 26657) only.
+
+```python
+import os
+from aether_client import AetherClient, Key, fetch_paid, find_services, rate_service, withdraw_prepaid
+
+client = AetherClient("http://localhost:26657", "aether-testnet-1")
+key = Key.from_mnemonic(os.environ["AETHER_MNEMONIC"])  # same address as `aetherd keys add` / `agentmcp`
+
+sent = client.send(key, "aether1...", "0.5 AETH", memo="invoice-42")
+done = client.wait_for_transaction(sent.hash)            # confirmed | failed | pending (timeout)
+# Retrying after an error: client.rebroadcast(sent.signed) -- never a second send().
+
+res = fetch_paid(client, key, "https://api.example.com/forecast", max_amount="0.05 AETH", prepay="1 AETH")
+# Or, where offered, pay from your own account under a capped, 7-day allowance the seller collects from later:
+res2 = fetch_paid(client, key, "https://api.example.com/forecast", max_amount="0.05 AETH", pull_allowance="1 AETH")
+services = find_services(client, query="weather", max_price="0.1 AETH", trusted=[owner_address])
+# services[i].reputation: payments, payers, ratings (can be faked), trusted_ratings (can't)
+# res.receipt: the seller's signed receipt and whether it matches exactly what was sent and received
+rate_service(client, key, "https://api.example.com", 5)  # only raters who paid a service count
+back = withdraw_prepaid(client, key, "https://api.example.com", withdrawal_id="w1")  # unspent prepaid balance
+```
+
+## Selling
+
+Charge per request from a Python service -- all three payment schemes, the `/.well-known/x402` manifest for the service directory, and withdrawals of unspent prepaid balances. Compatible with the Go paywall and every Aether buyer.
+
+```python
+import os
+from fastapi import FastAPI, Request
+from aether_client import AetherClient, Key, Paywall
+
+client = AetherClient("http://localhost:26657", "aether-testnet-1")
+pw = Paywall(client, "aether1...", "0.01 AETH", name="Weather", description="Forecasts by city",
+             prepaid_ledger="ledger.json",           # customers' balances: back it up
+             min_deposit="0.1 AETH",
+             payout_key=Key.from_mnemonic(os.environ["PAYOUT_MNEMONIC"]),  # pays withdrawals; keep a small float in it
+             receipt_key=payee_key,  # sign a receipt for every paid response (or a delegated key + receipt_delegation)
+             pull_collector_key=Key.from_mnemonic(os.environ["COLLECTOR_MNEMONIC"]), pull_credit="1 AETH")  # aether-pull: needs no funds
+pw.start_collecting()  # collects what aether-pull buyers owe, in batches
+api = FastAPI()
+
+@api.get("/forecast")
+async def forecast(request: Request):
+    return {"paid_by": request.scope["aether"].payer}
+
+app = pw.asgi(api, free=["/health"])   # Flask/Django: app.wsgi_app = pw.wsgi(app.wsgi_app); who paid: environ["aether.payment"]
+```
+
+The ledger is one JSON file (the Go paywall's format) for one process. Chain lookups block, so the ASGI adapter runs them in a thread.
+
+Amounts always carry a unit (`"1.5 AETH"`, `"1500000uaeth"`).
+
+**USDC.** `AetherClient(rpc, chain_id, usdc_channel="channel-N")` (Aether's end of its channel to Noble) also knows USDC: Noble's `uusdc` over exactly that channel, never a lookalike that arrived another way. For USDC that arrives another route, give its denom trace and its denom on the issuing chain instead: `usdc_path="transfer/channel-2", usdc_base_denom="erc20:0x0C382e685bbeeFE5d3d9C29e29E341fEE8E84C5d", usdc_issuer="Injective"` (`usdc_base_denom` defaults to `uusdc`). Then `send(key, to, "5 USDC")` sends USDC, `balances(address)` lists each asset, `wait_for_payment` matches in the asset of `min_amount`, and `fetch_paid` pays services priced in USDC with `max_amount` (and `prepay` / `pull_allowance`) in USDC; an amount in another asset than the service charges is refused with `ASSET_MISMATCH` before anything is paid. Results carry `asset`, `amount`, `balance`, `owed` and `allowance` in that asset's base units; the `*_uaeth` fields are set only for AETH. Without the channel, `"5 USDC"` is an unknown unit. The seller kit charges USDC too: `Paywall(client, pay_to, "0.05 USDC", usdc_channel="channel-N")` charges Noble USDC for everything (payments, deposits and balances, pull allowances and collections, withdrawals), `min_deposit` and `pull_credit` must then be in USDC, and 402s, the manifest and receipts carry the asset exactly as `cmd/paywall`'s do.
+
+Tests: `python -m unittest discover -s tests` (checked against `../testdata/vectors.json`, generated by the Go code).

aether_chain_client-0.2.9/aether_chain_client.egg-info/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: aether-chain-client
+Version: 0.2.9
+Summary: Python client for the Aether chain: ML-DSA-44 keys, payments, buying and selling paid APIs (x402 aether-memo / aether-prepaid) and the service directory.
+License: MIT
+Project-URL: Homepage, https://github.com/whoyoujoshin/aether/tree/main/clients/python#readme
+Project-URL: Repository, https://github.com/whoyoujoshin/aether
+Project-URL: Issues, https://github.com/whoyoujoshin/aether/issues
+Keywords: aether,ai-agents,agent-payments,x402,mcp,blockchain,cosmos,post-quantum,ml-dsa,usdc
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: dilithium-py<2,>=1.4
+Requires-Dist: mnemonic>=0.21
+
+# aether-chain-client
+
+Python client for the [Aether](https://github.com/whoyoujoshin/aether) chain: ML-DSA-44 keys, sending and receiving AETH, buying from and selling paid APIs (x402 `aether-memo`, `aether-prepaid` and `aether-pull`) and the on-chain service directory. It talks to a node's CometBFT RPC (port 26657) only.
+
+```python
+import os
+from aether_client import AetherClient, Key, fetch_paid, find_services, rate_service, withdraw_prepaid
+
+client = AetherClient("http://localhost:26657", "aether-testnet-1")
+key = Key.from_mnemonic(os.environ["AETHER_MNEMONIC"])  # same address as `aetherd keys add` / `agentmcp`
+
+sent = client.send(key, "aether1...", "0.5 AETH", memo="invoice-42")
+done = client.wait_for_transaction(sent.hash)            # confirmed | failed | pending (timeout)
+# Retrying after an error: client.rebroadcast(sent.signed) -- never a second send().
+
+res = fetch_paid(client, key, "https://api.example.com/forecast", max_amount="0.05 AETH", prepay="1 AETH")
+# Or, where offered, pay from your own account under a capped, 7-day allowance the seller collects from later:
+res2 = fetch_paid(client, key, "https://api.example.com/forecast", max_amount="0.05 AETH", pull_allowance="1 AETH")
+services = find_services(client, query="weather", max_price="0.1 AETH", trusted=[owner_address])
+# services[i].reputation: payments, payers, ratings (can be faked), trusted_ratings (can't)
+# res.receipt: the seller's signed receipt and whether it matches exactly what was sent and received
+rate_service(client, key, "https://api.example.com", 5)  # only raters who paid a service count
+back = withdraw_prepaid(client, key, "https://api.example.com", withdrawal_id="w1")  # unspent prepaid balance
+```
+
+## Selling
+
+Charge per request from a Python service -- all three payment schemes, the `/.well-known/x402` manifest for the service directory, and withdrawals of unspent prepaid balances. Compatible with the Go paywall and every Aether buyer.
+
+```python
+import os
+from fastapi import FastAPI, Request
+from aether_client import AetherClient, Key, Paywall
+
+client = AetherClient("http://localhost:26657", "aether-testnet-1")
+pw = Paywall(client, "aether1...", "0.01 AETH", name="Weather", description="Forecasts by city",
+             prepaid_ledger="ledger.json",           # customers' balances: back it up
+             min_deposit="0.1 AETH",
+             payout_key=Key.from_mnemonic(os.environ["PAYOUT_MNEMONIC"]),  # pays withdrawals; keep a small float in it
+             receipt_key=payee_key,  # sign a receipt for every paid response (or a delegated key + receipt_delegation)
+             pull_collector_key=Key.from_mnemonic(os.environ["COLLECTOR_MNEMONIC"]), pull_credit="1 AETH")  # aether-pull: needs no funds
+pw.start_collecting()  # collects what aether-pull buyers owe, in batches
+api = FastAPI()
+
+@api.get("/forecast")
+async def forecast(request: Request):
+    return {"paid_by": request.scope["aether"].payer}
+
+app = pw.asgi(api, free=["/health"])   # Flask/Django: app.wsgi_app = pw.wsgi(app.wsgi_app); who paid: environ["aether.payment"]
+```
+
+The ledger is one JSON file (the Go paywall's format) for one process. Chain lookups block, so the ASGI adapter runs them in a thread.
+
+Amounts always carry a unit (`"1.5 AETH"`, `"1500000uaeth"`).
+
+**USDC.** `AetherClient(rpc, chain_id, usdc_channel="channel-N")` (Aether's end of its channel to Noble) also knows USDC: Noble's `uusdc` over exactly that channel, never a lookalike that arrived another way. For USDC that arrives another route, give its denom trace and its denom on the issuing chain instead: `usdc_path="transfer/channel-2", usdc_base_denom="erc20:0x0C382e685bbeeFE5d3d9C29e29E341fEE8E84C5d", usdc_issuer="Injective"` (`usdc_base_denom` defaults to `uusdc`). Then `send(key, to, "5 USDC")` sends USDC, `balances(address)` lists each asset, `wait_for_payment` matches in the asset of `min_amount`, and `fetch_paid` pays services priced in USDC with `max_amount` (and `prepay` / `pull_allowance`) in USDC; an amount in another asset than the service charges is refused with `ASSET_MISMATCH` before anything is paid. Results carry `asset`, `amount`, `balance`, `owed` and `allowance` in that asset's base units; the `*_uaeth` fields are set only for AETH. Without the channel, `"5 USDC"` is an unknown unit. The seller kit charges USDC too: `Paywall(client, pay_to, "0.05 USDC", usdc_channel="channel-N")` charges Noble USDC for everything (payments, deposits and balances, pull allowances and collections, withdrawals), `min_deposit` and `pull_credit` must then be in USDC, and 402s, the manifest and receipts carry the asset exactly as `cmd/paywall`'s do.
+
+Tests: `python -m unittest discover -s tests` (checked against `../testdata/vectors.json`, generated by the Go code).

aether_chain_client-0.2.9/aether_chain_client.egg-info/SOURCES.txt

@@ -0,0 +1,27 @@
+README.md
+pyproject.toml
+aether_chain_client.egg-info/PKG-INFO
+aether_chain_client.egg-info/SOURCES.txt
+aether_chain_client.egg-info/dependency_links.txt
+aether_chain_client.egg-info/requires.txt
+aether_chain_client.egg-info/top_level.txt
+aether_client/__init__.py
+aether_client/amount.py
+aether_client/bech32.py
+aether_client/client.py
+aether_client/directory.py
+aether_client/keys.py
+aether_client/ledger.py
+aether_client/paywall.py
+aether_client/proto.py
+aether_client/receipt.py
+aether_client/rpc.py
+aether_client/seller.py
+aether_client/tx.py
+aether_client/withdraw.py
+tests/test_contract.py
+tests/test_pull.py
+tests/test_reputation.py
+tests/test_seller.py
+tests/test_usdc.py
+tests/test_vectors.py

aether_chain_client-0.2.9/aether_chain_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aether_chain_client-0.2.9/aether_chain_client.egg-info/requires.txt

@@ -0,0 +1,2 @@
+dilithium-py<2,>=1.4
+mnemonic>=0.21

aether_chain_client-0.2.9/aether_chain_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+aether_client

aether_chain_client-0.2.9/aether_client/__init__.py

@@ -0,0 +1,19 @@
+"""Python client for the Aether chain."""
+
+from .amount import (AETH, DENOM, Asset, Assets, decimal_of, format_aeth, format_amount, parse_amount, parse_uaeth, receipt_amount,
+                     usdc, usdc_at, usdc_for, DEFAULT_USDC_BASE_DENOM)
+from .client import AetherClient, IncomingPayment, SendGrant, SendResult, TransactionInfo, Transfer, decode_send_grant, transfers
+from .directory import (ANNOUNCE_PREFIX, DEFAULT_WINDOW, DELIST_PREFIX, DIRECTORY_ADDRESS, RATE_PREFIX, Rating, RatingSummary, Reputation,
+                        Service, fetch_manifest, find_services, normalize_url, rate_service, rating_memo)
+from .keys import PREFIX, Key, address_bytes, address_of, is_address
+from .paywall import (DEPOSIT_MEMO_PREFIX, PULL_GRANT_SECONDS, SCHEME_MEMO, SCHEME_PREPAID, SCHEME_PULL, FetchPaidResult, PaymentError,
+                      fetch_paid, memo_payment_header, prepaid_payment_header, present_payment, pull_payment_header,
+                      pull_signing_message, signing_message)
+from .rpc import Rpc, RpcError
+from .tx import (DEFAULT_GAS_LIMIT, MSG_EXEC_TYPE_URL, MSG_GRANT_TYPE_URL, SignedTx, build_send, build_tx, exec_send_msg,
+                 grant_send_msg, memo_of)
+from .withdraw import WithdrawResult, withdraw_prepaid
+from .ledger import FileLedger, LedgerError
+from .seller import WITHDRAW_PATH, KeyPayout, Payment, Paywall, Respond, SellerRequest, Serve
+from .receipt import (RECEIPT_HEADER, ReceiptCheck, check_receipt, create_receipt_delegation, decode_receipt,
+                      delegation_signing_message, receipt_signing_message, sign_receipt, verify_receipt)

aether_chain_client-0.2.9/aether_client/amount.py

@@ -0,0 +1,198 @@
+"""Amounts carry a unit: "1.5 AETH" or "1500000uaeth" (1 AETH = 1,000,000 uaeth).
+
+A bare number is refused rather than guessed at -- mixing the two up is a
+million-fold error with real money.
+"""
+
+import hashlib
+import re
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+DENOM = "uaeth"
+_DECIMALS = 6
+_PATTERN = re.compile(r"^\s*([0-9]+)(?:\.([0-9]+))?\s*([A-Za-z]+)\s*$")
+_MAX = (1 << 63) - 1
+
+
+def parse_amount(s: str) -> int:
+    """Parses an amount with its unit into uaeth."""
+    m = _PATTERN.match(s)
+    if not m:
+        if re.fullmatch(r"\s*[0-9]+\s*", s):
+            raise ValueError(f'amount "{s}" has no unit: write e.g. "1.5 AETH" or "1500000uaeth" (1 AETH = 1,000,000 uaeth)')
+        raise ValueError(f'invalid amount "{s}": write e.g. "1.5 AETH" or "1500000uaeth"')
+    whole, frac, unit = m.group(1), m.group(2) or "", m.group(3).lower()
+    if unit == "aeth":
+        if len(frac) > _DECIMALS:
+            raise ValueError(f'amount "{s}" has more than {_DECIMALS} decimal places')
+        v = int(whole + frac.ljust(_DECIMALS, "0"), 10)
+    elif unit == DENOM:
+        if frac:
+            raise ValueError(f'amount "{s}": uaeth can\'t be fractional')
+        v = int(whole, 10)
+    else:
+        raise ValueError(f'amount "{s}" has unknown unit "{m.group(3)}": use AETH or uaeth')
+    if v <= 0:
+        raise ValueError(f'amount "{s}" must be greater than zero')
+    if v > _MAX:
+        raise ValueError(f'amount "{s}" is too large')
+    return v
+
+
+def parse_uaeth(s: str) -> int:
+    """A strictly base-10 whole number of uaeth ("1500000"), as wire formats carry it."""
+    if not re.fullmatch(r"[0-9]+", s or ""):
+        raise ValueError(f'invalid uaeth amount "{s}"')
+    return int(s, 10)
+
+
+def format_aeth(uaeth: int) -> str:
+    """1500000 -> "1.5"."""
+    sign = "-" if uaeth < 0 else ""
+    a = abs(uaeth)
+    frac = str(a % 1_000_000).rjust(_DECIMALS, "0").rstrip("0")
+    return sign + str(a // 1_000_000) + ("." + frac if frac else "")
+
+
+@dataclass(frozen=True)
+class Asset:
+    """A token the client knows by name. Amounts name their asset by unit ("5 USDC", "1.5 AETH",
+    "5000000uusdc"), so a USDC amount can never be read as AETH or the other way round."""
+    symbol: str  # what people write: "AETH", "USDC"
+    denom: str  # the chain's name for it: "uaeth", or "ibc/<hash>" for a token that arrived over IBC
+    base_unit: str  # the smallest unit's name, which people may also write: "uaeth", "uusdc"
+    decimals: int  # how many base units make one symbol, as a power of ten
+    origin: str  # "Aether"; for USDC, its issuer and route, like "Noble over transfer/channel-3"
+
+
+AETH = Asset("AETH", DENOM, DENOM, _DECIMALS, "Aether")
+
+
+DEFAULT_USDC_BASE_DENOM = "uusdc"  # USDC's denom on Noble, which issues it
+
+_HOP = re.compile(r"[a-zA-Z0-9._+\-#\[\]<>]{2,128}/channel-[0-9]+")
+_BASE_DENOM = re.compile(r"[a-zA-Z][a-zA-Z0-9/:._-]{2,127}")
+
+
+def usdc(channel: str) -> Asset:
+    """Noble's USDC as it exists on Aether after crossing channel, the Aether end of Aether's own
+    channel to Noble. It's usdc_at with a single hop and Noble's base denom."""
+    if not re.fullmatch(r"channel-[0-9]+", channel or ""):
+        raise ValueError(f'USDC channel "{channel}": want Aether\'s end of its channel to Noble, like channel-3')
+    return usdc_at(f"transfer/{channel}", DEFAULT_USDC_BASE_DENOM)
+
+
+def usdc_at(path: str, base_denom: str) -> Asset:
+    """The USDC that reaches Aether along path, its ICS-20 denom trace as Aether records it (Aether's
+    own hop first), with base_denom its denom on the chain that issues it: "transfer/channel-1/
+    transfer/channel-4280" and "uusdc" for Noble's USDC through Osmosis, say. The same token reaching
+    Aether any other way has a different denom and isn't interchangeable with it, so it's never
+    accepted as USDC. base_denom is case-sensitive."""
+    hops = (path or "").split("/")
+    if not path or len(hops) % 2:
+        raise ValueError(f'USDC path "{path}": want port/channel hops from Aether\'s end, like transfer/channel-1/transfer/channel-4280')
+    for i in range(0, len(hops), 2):
+        hop = f"{hops[i]}/{hops[i + 1]}"
+        if not _HOP.fullmatch(hop):
+            raise ValueError(f'USDC path "{path}": hop "{hop}" isn\'t port/channel-N')
+    if (base_denom or "").startswith("ibc/") or not _BASE_DENOM.fullmatch(base_denom or ""):
+        raise ValueError(f'USDC base denom "{base_denom}": want its denom on the chain that issues it, like uusdc, not an ibc/ hash')
+    h = hashlib.sha256(f"{path}/{base_denom}".encode()).hexdigest().upper()
+    issuer = "Noble" if base_denom == DEFAULT_USDC_BASE_DENOM else base_denom
+    return Asset("USDC", f"ibc/{h}", "uusdc", 6, f"{issuer} over {path}")
+
+
+def usdc_for(usdc_channel: Optional[str] = None, usdc_path: Optional[str] = None,
+             usdc_base_denom: Optional[str] = None, usdc_issuer: Optional[str] = None) -> Optional[Asset]:
+    """Which USDC a client accepts: usdc_channel, as shorthand for Noble's USDC over Aether's direct
+    channel to Noble, or usdc_path and usdc_base_denom for any other route or issuer (usdc_base_denom
+    defaults to uusdc). None of them: no USDC. usdc_issuer names the issuer in the asset's origin,
+    which tools label USDC by ("USDC (Injective)"); default Noble for uusdc, else the base denom."""
+    u: Optional[Asset] = None
+    if usdc_channel and (usdc_path or usdc_base_denom):
+        raise ValueError("set either usdc_channel or usdc_path and usdc_base_denom, not both")
+    if usdc_channel:
+        u = usdc(usdc_channel)
+    elif usdc_path:
+        u = usdc_at(usdc_path, usdc_base_denom or DEFAULT_USDC_BASE_DENOM)
+    elif usdc_base_denom:
+        raise ValueError(f'USDC base denom "{usdc_base_denom}" needs usdc_path too')
+    if not usdc_issuer:
+        return u
+    if u is None:
+        raise ValueError(f'USDC issuer "{usdc_issuer}" needs usdc_channel or usdc_path too')
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,31}", usdc_issuer):
+        raise ValueError(f'USDC issuer "{usdc_issuer}": want one word, like Injective')
+    return Asset(u.symbol, u.denom, u.base_unit, u.decimals, f"{usdc_issuer} over {u.origin.split(' over ', 1)[1]}")
+
+
+def decimal_of(asset: Asset, base: int) -> str:
+    """Base units as a decimal amount without trailing zeros or symbol: 1500000 -> "1.5"."""
+    sign = "-" if base < 0 else ""
+    a = abs(base)
+    if asset.decimals == 0:
+        return sign + str(a)
+    one = 10 ** asset.decimals
+    frac = str(a % one).rjust(asset.decimals, "0").rstrip("0")
+    return sign + str(a // one) + ("." + frac if frac else "")
+
+
+def format_amount(asset: Asset, base: int) -> str:
+    """Base units with the asset's symbol: 1500000 -> "1.5 USDC"."""
+    return f"{decimal_of(asset, base)} {asset.symbol}"
+
+
+def receipt_amount(amount: int, denom: str = DENOM) -> str:
+    """How a signed receipt states an amount: bare uaeth for AETH, else the amount followed by the denom."""
+    return str(amount) if denom in ("", DENOM) else f"{amount}{denom}"
+
+
+class Assets:
+    """The assets a client accepts: AETH always, and the USDC its setting names, if any (see usdc_for)."""
+
+    def __init__(self, usdc_channel: Optional[str] = None, usdc_path: Optional[str] = None,
+                 usdc_base_denom: Optional[str] = None, usdc_issuer: Optional[str] = None):
+        self._all: List[Asset] = [AETH]
+        u = usdc_for(usdc_channel, usdc_path, usdc_base_denom, usdc_issuer)
+        if u:
+            self._all.append(u)
+
+    def list(self) -> List[Asset]:
+        """Every asset, AETH first."""
+        return list(self._all)
+
+    def by_symbol(self, symbol: str) -> Optional[Asset]:
+        return next((a for a in self._all if a.symbol.lower() == symbol.lower()), None)
+
+    def by_denom(self, denom: str) -> Optional[Asset]:
+        return next((a for a in self._all if a.denom == denom), None)
+
+    def parse(self, s: str) -> Tuple[Asset, int]:
+        """Reads an amount with its unit: a symbol with up to its decimals ("1.5 AETH", "2.25usdc")
+        or a whole number of base units ("2250000 uusdc"). A bare number, or a unit it doesn't know,
+        is refused. Returns the asset and the amount in its base units."""
+        m = _PATTERN.match(s)
+        if not m:
+            if re.fullmatch(r"\s*[0-9]+(\.[0-9]+)?\s*", s):
+                raise ValueError(f'amount "{s}" has no unit: write e.g. "1.5 AETH" or "1500000uaeth"')
+            raise ValueError(f'invalid amount "{s}": write e.g. "1.5 AETH" or "1500000uaeth"')
+        whole, frac, unit = m.group(1), m.group(2) or "", m.group(3).lower()
+        for a in self._all:
+            if unit == a.symbol.lower():
+                if len(frac) > a.decimals:
+                    raise ValueError(f'amount "{s}" has more than {a.decimals} decimal places')
+                v = int(whole + frac.ljust(a.decimals, "0"), 10)
+            elif unit == a.base_unit.lower():
+                if frac:
+                    raise ValueError(f'amount "{s}": {a.base_unit} is the smallest unit and can\'t be fractional')
+                v = int(whole, 10)
+            else:
+                continue
+            if v <= 0:
+                raise ValueError(f'amount "{s}" must be greater than zero')
+            if v > _MAX:
+                raise ValueError(f'amount "{s}" is too large')
+            return a, v
+        units = ", ".join(u for a in self._all for u in (a.symbol, a.base_unit))
+        raise ValueError(f'amount "{s}" has unknown unit "{m.group(3)}": use {units}')

aether_chain_client-0.2.9/aether_client/bech32.py

@@ -0,0 +1,64 @@
+"""Bech32 (BIP-173), as Cosmos addresses use it."""
+
+CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l"
+_GEN = (0x3B6A57B2, 0x26508E6D, 0x1EA119FA, 0x3D4233DD, 0x2A1462B3)
+
+
+def _polymod(values):
+    chk = 1
+    for v in values:
+        top = chk >> 25
+        chk = (chk & 0x1FFFFFF) << 5 ^ v
+        for i in range(5):
+            chk ^= _GEN[i] if (top >> i) & 1 else 0
+    return chk
+
+
+def _hrp_expand(hrp):
+    return [ord(c) >> 5 for c in hrp] + [0] + [ord(c) & 31 for c in hrp]
+
+
+def _convertbits(data, frombits, tobits, pad):
+    acc = bits = 0
+    out = []
+    maxv = (1 << tobits) - 1
+    for value in data:
+        if value < 0 or value >> frombits:
+            raise ValueError("bech32: invalid value")
+        acc = (acc << frombits) | value
+        bits += frombits
+        while bits >= tobits:
+            bits -= tobits
+            out.append((acc >> bits) & maxv)
+    if pad:
+        if bits:
+            out.append((acc << (tobits - bits)) & maxv)
+    elif bits >= frombits or ((acc << (tobits - bits)) & maxv):
+        raise ValueError("bech32: invalid padding")
+    return out
+
+
+def encode(hrp: str, data: bytes) -> str:
+    words = _convertbits(data, 8, 5, True)
+    values = _hrp_expand(hrp) + words
+    polymod = _polymod(values + [0] * 6) ^ 1
+    checksum = [(polymod >> 5 * (5 - i)) & 31 for i in range(6)]
+    return hrp + "1" + "".join(CHARSET[d] for d in words + checksum)
+
+
+def decode(s: str):
+    """Returns (hrp, data bytes); raises ValueError if invalid."""
+    if s.lower() != s and s.upper() != s:
+        raise ValueError("bech32: mixed case")
+    s = s.lower()
+    pos = s.rfind("1")
+    if pos < 1 or pos + 7 > len(s):
+        raise ValueError("bech32: bad separator")
+    hrp, rest = s[:pos], s[pos + 1:]
+    try:
+        values = [CHARSET.index(c) for c in rest]
+    except ValueError:
+        raise ValueError("bech32: invalid character") from None
+    if _polymod(_hrp_expand(hrp) + values) != 1:
+        raise ValueError("bech32: bad checksum")
+    return hrp, bytes(_convertbits(values[:-6], 5, 8, False))