Metadata-Version: 2.5
Name: qorechain-sdk
Version: 0.14.0
Summary: Python SDK for QoreChain - typed messages for every module, queries, auto-gas, tx tracking, subscriptions, accounts (native/EVM/SVM), and post-quantum signing.
Project-URL: Homepage, https://github.com/qorechain/qorechain-sdk
Project-URL: Repository, https://github.com/qorechain/qorechain-sdk
Project-URL: Issues, https://github.com/qorechain/qorechain-sdk/issues
Author-email: Liviu Epure <liviu.etty@gmail.com>
License-Expression: Apache-2.0
Keywords: blockchain,cosmos,dilithium,evm,ml-dsa,post-quantum,qorechain,svm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: base58<3,>=2.1
Requires-Dist: bech32<2,>=1.2
Requires-Dist: bip-utils<3,>=2.9
Requires-Dist: cosmpy<1,>=0.11
Requires-Dist: dilithium-py>=1.1
Requires-Dist: httpx<1,>=0.27
Requires-Dist: websockets<16,>=12
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# qorechain (Python SDK)

A typed Python SDK for QoreChain - typed messages for every module, typed query
clients, auto-gas, tx tracking, error decoding, block/tx search, websocket
subscriptions, network presets, denom/address utilities, HD account derivation
(native / EVM / SVM), post-quantum (ML-DSA-87) signing, and read clients (REST +
`qor_` JSON-RPC). It mirrors the QoreChain TypeScript SDK surface with idiomatic
Python.

## Install

```bash
pip install qorechain-sdk
```

Python 3.10+ is required. The package ships type hints and a `py.typed` marker.

## Quickstart

### Connect a client

```python
from qorsdk import create_client

# Defaults to the testnet preset (the public testnet endpoints).
client = create_client()
print(client.network.chain_id)  # "qorechain-diana"

# Read account balances over REST.
balances = client.rest.get_all_balances("qor15yk64u7zc9g9k2yr2wmzeva5qgwxps6yjecvvu")

# Call the qor_ JSON-RPC namespace.
stats = client.qor.get_ai_stats()

# Estimate a fee (AI oracle with a deterministic static fallback).
fee = client.fees.estimate("fast")

client.close()
```

### Network presets (v0.12.0)

| Preset | Chain id | REST, RPC, EVM | EVM WebSocket | gRPC, SVM |
|---|---|---|---|---|
| `mainnet` | `qorechain-vladi` (EVM 9801) | public | not offered (poll `evm_rpc`) | not preset |
| `testnet` | `qorechain-diana` (EVM 9800) | public | public | not preset |
| `localnet` | `qorechain-devnet` | `localhost` (1317, 26657, 8545) | `ws://localhost:8546` | `localhost` (9090, 8899) |

The public hostnames are defined once, in `qorsdk.networks.PUBLIC_ENDPOINTS`
(`get_network("mainnet").endpoints.rest` and so on). `endpoints` overrides any
single endpoint, as before:

```python
from qorsdk import create_client, require_endpoint

client = create_client(network="mainnet")
client = create_client(network="mainnet", endpoints={"rest": "https://my-node.example:1317"})
client = create_client(network="localnet")  # the localhost defaults of earlier releases

# An endpoint the preset leaves unset is None. Code that needs it raises
# EndpointNotConfiguredError (a ValueError) instead of falling back to localhost:
require_endpoint(client.network, "grpc")
```

- **Behaviour change in 0.12.0:** `mainnet` and `testnet` used to default to
  localhost. To keep talking to a local node, use `network="localnet"` or pass
  `endpoints`.
- The testnet endpoints are rate limited per IP at the edge. For production
  traffic, run or use your own node and pass its URLs as `endpoints`.
- SVM transactions are not open on either network, so no SVM endpoint is preset.
- `https://download.qore.host/<network>/latest.json` is a release manifest
  (version, peers, state sync), not an endpoint.

### Which chain release a network runs

Nodes do not report their binary version: `node_info`'s `application_version`
is empty on purpose, so a node cannot be fingerprinted by release. Detect a
feature by its upgrade plan instead, with `is_upgrade_applied(rest, name)`
(`GET /cosmos/upgrade/v1beta1/applied_plan/<name>`, height above 0 = applied),
and ask for EVERY plan name that can carry it, since the networks did not all
use the same names:

- mainnet has applied `v3.2.5` (height 3,906,833); the testnet has applied
  `v3.2.5` and `v3.2.6`;
- the sign-bytes v2 change is `v3.2.0` on mainnet and `v3.1.98` on the testnet
  (the SDK asks for both).

For a human-readable version, read `.version` from
`https://download.qore.host/<network>/latest.json` (`mainnet` or `testnet`).

### Derive accounts

```python
from qorsdk import (
    generate_mnemonic,
    derive_native_account,
    derive_evm_account,
    derive_svm_account,
)

mnemonic = generate_mnemonic()  # 12 words; use generate_mnemonic(256) for 24

native = derive_native_account(mnemonic, 0)  # qor1...
evm = derive_evm_account(mnemonic, 0)        # 0x... (EIP-55 checksummed)
svm = derive_svm_account(mnemonic, 0)        # base58 ed25519 pubkey

print(native.address, evm.address, svm.address)
```

Derivation schemes:

| Type   | Curve     | Path                  | Address |
| ------ | --------- | --------------------- | ------- |
| native | secp256k1 | `m/44'/118'/0'/0/{i}` | bech32 `qor` of `ripemd160(sha256(pubkey))` |
| evm    | secp256k1 | `m/44'/60'/0'/0/{i}`  | `0x` + `keccak256(pubkey)[-20:]`, EIP-55 |
| svm    | ed25519   | `m/44'/501'/{i}'/0'`  | base58 of the 32-byte public key |

The mnemonic is validated (words **and** checksum) before any key is derived, so
a typo'd phrase raises rather than silently producing a wrong account.

### Denomination math

```python
from qorsdk import to_base, from_base

to_base("1.5")        # "1500000"  (QOR -> uqor, exponent 6)
from_base("1500000")  # "1.5"
```

All conversions use integer arithmetic - never floats - so they are exact.

### Post-quantum signing (ML-DSA-87 / Dilithium-5)

```python
from qorsdk import (
    generate_pqc_keypair,
    pqc_sign,
    pqc_verify,
    build_hybrid_signature_extension,
    ALGORITHM_DILITHIUM5,
)

kp = generate_pqc_keypair()           # public 2592 B, secret 4896 B
sig = pqc_sign(kp.secret_key, b"msg") # signature 4627 B
assert pqc_verify(kp.public_key, b"msg", sig)

# Build the on-chain hybrid-signature extension (protobuf-encoded into Any.value).
ext = build_hybrid_signature_extension(ALGORITHM_DILITHIUM5, sig, kp.public_key)
```

Sizes are **strict**: `pqc_verify` returns `False` for any signature that is not
exactly 4627 bytes or any public key that is not exactly 2592 bytes (a truncated
signature and one with an extra trailing byte are both rejected), and `pqc_sign`
raises on a secret key that is not exactly 4896 bytes. The SDK checks this itself
rather than trusting the library underneath, so QoreChain's bindings cannot
disagree about whether an over-long signature is valid.

### Async clients

```python
import asyncio
from qorsdk import AsyncRestClient, AsyncQorClient

async def main():
    async with AsyncRestClient("http://localhost:1317") as rest:
        await rest.get_ai_stats()
    async with AsyncQorClient("http://localhost:8545") as qor:
        await qor.get_tokenomics_overview()

asyncio.run(main())
```

### Typed messages for every module

`msg.<module>.<name>(...)` builds any of the chain's 61 custom messages (across
amm / bridge / rdk / multilayer / pqc / svm / lightnode / license /
abstractaccount / crossvm / rlconsensus) plus the standard Native modules
(bank / staking / distribution / gov / authz / feegrant / ibc). Each returns a
`Msg` (`{type_url, value}`) you pass to `send_messages` or the hybrid PQC path.

```python
from cosmpy.protos.cosmos.base.v1beta1.coin_pb2 import Coin
from qorsdk import msg, send_messages, build_hybrid_tx, generate_pqc_keypair

swap = msg.amm.swap_exact_in(
    sender=native.address,
    pool_id=1,
    token_in=Coin(denom="uqor", amount="1000000"),
    denom_out="uusdc",
    min_out="990000",
)
delegate = msg.staking.delegate(delegator_address=native.address, validator_address="qorvaloper1...")

# Classical tx carrying any messages.
built = send_messages(
    account=native, messages=[swap, delegate],
    chain_id="qorechain-diana", account_number=0, sequence=0,
    fee={"amount": [{"denom": "uqor", "amount": "5000"}], "gas": "200000"},
)

# Or a hybrid (classical + ML-DSA-87) tx over the same messages.
# The testnet verifies the v2 sign-bytes form (see "Hybrid sign-bytes v1 / v2").
hybrid = build_hybrid_tx(
    account=native, pqc_keypair=generate_pqc_keypair(), messages=[swap],
    fee={"amount": [{"denom": "uqor", "amount": "5000"}], "gas": "200000"},
    chain_id="qorechain-diana", account_number=0, sequence=0,
    sign_bytes_version="v2",
)
```

The `qorechain_registry()` type-URL → proto map and `decode_any(type_url, value)`
let you parse any supported message back into a typed object.

### Typed query clients (gRPC)

Modules with a `Query` service (crossvm, lightnode, pqc, qca, reputation,
rlconsensus, svm) expose typed callers over a gRPC channel. Chain v3.1.83 adds
`amm`, `license`, and `abstractaccount` typed query clients, the `multilayer`
`anchor` / `anchors` state-anchor queries, and abstractaccount
`register_authenticator` / `revoke_authenticator` message composers:

```python
from qorsdk import connect_query_clients

with connect_query_clients("localhost:9090") as q:
    res = q.crossvm.message("msg-123")     # -> QueryMessageResponse
    node = q.lightnode.light_node(native.address)
    acct = q.pqc.account(native.address)
```

### Sidechains, paychains & rollups (v0.4.0)

The multilayer (sidechains/paychains) and `rdk` (rollup) modules are covered by
typed message composers and typed query clients. Compose a write with
`msg.multilayer.*` / `msg.rdk.*` and broadcast it like any other message; read
layer and rollup state through the typed gRPC clients.

```python
from qorsdk import msg, send_messages, connect_query_clients

# Multilayer: register a sidechain / paychain, anchor state, route a tx.
register = msg.multilayer.register_sidechain(
    creator=native.address, layer_id="game-l2", description="game sidechain",
)
route = msg.multilayer.route_transaction(
    sender=native.address, transaction_payload=b"...", preferred_layer="game-l2",
)

# Rollups (rdk): create a rollup, submit a batch, execute a withdrawal.
create = msg.rdk.create_rollup(
    creator=native.address, rollup_id="r1", profile="default", vm_type="evm",
)
withdraw = msg.rdk.execute_withdrawal(
    submitter=native.address, rollup_id="r1", batch_index=0, withdrawal_index=0,
    recipient="qor1rcpt", denom="uqor", amount=100, proof=[b"\x01"],
)

# Typed reads over gRPC (multilayer / rdk / bridge / crossvm query services).
with connect_query_clients("localhost:9090") as q:
    layer = q.multilayer.layer("game-l2")
    layers = q.multilayer.layers()
    stats = q.multilayer.routing_stats()
    rollup = q.rdk.rollup("r1")
    batch = q.rdk.latest_batch("r1")
```

See the [multilayer](https://github.com/qorechain/qorechain-sdk/blob/main/docs/docs/guides/multilayer.md) and
[rollups](https://github.com/qorechain/qorechain-sdk/blob/main/docs/docs/guides/rollups.md) guides.

### AI pre-flight risk scoring (v0.5.0)

QoreChain exposes an on-chain AI risk/anomaly model over two EVM precompiles, so
you can get an advisory verdict on a transaction before broadcasting it. The
helpers in `qorsdk.precompiles` issue plain `eth_call`s through any
`eth_call`-capable client (e.g. a [web3.py](https://web3py.readthedocs.io) provider
pointed at the network's `evm_rpc`).

```python
from qorsdk import (
    simulate_with_risk_score, ai_risk_score, ai_anomaly_check,
    PRECOMPILE_AI_RISK_SCORE,     # 0x…0B01
    PRECOMPILE_AI_ANOMALY_CHECK,  # 0x…0B02
)

# Combined gas + risk + anomaly pre-flight.
verdict = simulate_with_risk_score(eth_client, {
    "from": "0xSender", "to": "0xContract", "data": "0x…", "value": 0,
})
if not verdict["safe"]:
    raise RuntimeError("AI pre-flight flagged this transaction")

# Or call the precompiles individually.
risk = ai_risk_score(eth_client, b"\xde\xad\xbe\xef")  # {"score", "level"}
anomaly = ai_anomaly_check(eth_client, "0xSender", 1_000_000)  # {"anomaly_score", "flagged"}
```

See the [AI pre-flight](https://docs.qorechain.io/sdk/guides/ai-preflight) guide.

### Unified cross-VM calls (v0.5.0)

`CrossVmClient` wraps `MsgCrossVMCall` so you can route a single call - or
several atomically in **one** transaction - across the EVM, CosmWasm, and SVM
VMs (`VM_TYPES`). The payload is raw bytes (`payload=`), a CosmWasm JSON message
(`cosmwasm=` is `json.dumps`'d to UTF-8), or SVM bytes (`svm=`).

```python
from qorsdk import (
    CrossVmCallOptions, create_cross_vm_client, build_cross_vm_call,
    decode_cross_vm_response, decode_cross_vm_responses,
)

xvm = create_cross_vm_client(account=native, ...)  # see docstring for context args

# Single call into a CosmWasm contract.
res = xvm.call(target_vm="cosmwasm", target_contract="qor1contract…",
               cosmwasm={"increment": {}})

# Atomic triple-VM batch in ONE tx.
atomic = xvm.call_atomic([
    CrossVmCallOptions(target_vm="evm", target_contract="0xC…", payload=abi_calldata),
    CrossVmCallOptions(target_vm="svm", target_contract="Prog…", svm=raw_bytes),
    CrossVmCallOptions(target_vm="cosmwasm", target_contract="qor1…",
                       cosmwasm={"stake": {}}),
])

status = xvm.get_message("42")  # read a routed message's status
```

**The callee's answer (chain v3.1.97).** A call executes inside the transaction
and returns its result; `decode_cross_vm_response` (or `…_responses`, one per
call, in message order) reads the `MsgCrossVMCallResponse` out of the committed
tx and gives you `message_id`, `executed`, `data` (the callee's return value) and
`gas_used`. Pass `async_=True` to queue the call for a later `MsgProcessQueue`
dispatch instead - a queued call comes back `executed=False` with no `data` yet.

```python
included = wait_for_tx(client.rest, res["tx_response"]["txhash"])
answer = decode_cross_vm_response(included)
answer.message_id, answer.executed, answer.data, answer.gas_used
```

`source_vm` is **ignored by the chain**, which derives the origin lane from the
execution context; it is still accepted (and sent, default `"evm"`) so older
nodes keep taking the message, but setting it has no on-chain effect.

`build_cross_vm_call(...)` is also available as a free function for hand-building
the message. See the [cross-VM](https://docs.qorechain.io/sdk/guides/cross-vm) guide.

### PQC key helpers (v0.5.0)

On the native lane QoreChain requires hybrid post-quantum signatures
(ML-DSA-87 + secp256k1) by default. `qorsdk.pqc_dx` registers the signer's PQC key in one idempotent call.

```python
import httpx
from qorsdk import (
    fetch_pqc_status, ensure_pqc_registered, migrate_to_hybrid, migrate_pqc_key,
    derive_native_account, derive_pqc_canonical, get_network,
)

REST = get_network("mainnet").endpoints.rest
native = derive_native_account(mnemonic, 0)
# The recoverable PQC key: derived from the same mnemonic, bound to the address.
pqc_keypair = derive_pqc_canonical(native.address, mnemonic)

# Read-only status over REST (served by every public endpoint).
status = fetch_pqc_status(REST, native.address)

# Idempotent: registers the signer's Dilithium key only if it isn't already,
# and raises PqcKeyMismatchError if another key is registered. It never
# registers blind: a second registration is refused after the fee is charged.
acct = httpx.get(f"{REST}/cosmos/auth/v1beta1/accounts/{native.address}").json()["account"]
result = ensure_pqc_registered(
    account=native,
    pqc_keypair=pqc_keypair,
    chain_id="qorechain-vladi",
    account_number=int(acct["account_number"]),
    sequence=int(acct.get("sequence", 0)),
    rest_url=REST,
    # Registration carries a 2592-byte key and, from chain v3.2.3, a
    # 4627-byte proof of possession: about 275k gas.
    fee={"amount": [{"denom": "uqor", "amount": "60000"}], "gas": "400000"},
)

# Migrate a classical account to hybrid signing, then sign hybrid.
path = migrate_to_hybrid(account=native, pqc_keypair=pqc_keypair, ...)

# Rotate an account's on-chain PQC key (MsgMigratePQCKey).
migrate_pqc_key(account=native, ...)
```

Async status reads are available as `is_pqc_registered_async` /
`get_pqc_status_async`. See the
[post-quantum hybrid signing](https://docs.qorechain.io/sdk/guides/quantum-safe) guide.

### Hybrid sign-bytes v1 / v2 (v0.8.1 / chain v3.2.0, testnet v3.1.98)

A hybrid transaction's ML-DSA-87 signature covers `B0` (the `TxBody` without the
PQC extension) and `A` (the `AuthInfo` bytes). Chain release **v3.2.0** - which
the testnet already took under the earlier name **v3.1.98** - changed the exact
bytes that are signed:

| Form | Signed bytes |
|---|---|
| v1 | `BE32(len B0) ‖ B0 ‖ BE32(len A) ‖ A` |
| v2 | `"qorechain-pqc-hybrid-v2" ‖ BE64(len chainID) ‖ chainID ‖ BE32(len B0) ‖ B0 ‖ BE32(len A) ‖ A` |

v2 adds a domain tag (a signature made in any other context can never pass as a
tx signature) and binds the chain-id (the post-quantum signature itself refuses
to verify on another network). Each network verifies **exactly one** form at any
height, with no overlap window, so the SDK must sign the form of the *target*
network:

- **Testnet** (`qorechain-diana`) applied the upgrade as **`v3.1.98`** at height
  5,746,000 and now accepts **only v2**.
- **Mainnet** (`qorechain-vladi`) applies the same handler as **`v3.2.0`**, at a
  height chosen by governance, and stays on **v1** until then.
- Any chain started on that release or later is v2 from its first block.

**The switch has two plan names, so ask for both.** `SIGN_BYTES_V2_UPGRADES ==
("v3.2.0", "v3.1.98")` (`SIGN_BYTES_V2_UPGRADE` is the primary, `"v3.2.0"`).
A client that asks only one name reads height 0 on the other network, signs v1,
and every hybrid transaction there is refused with `pqc` code 21.

The `"auto"` rule for `qorechain-vladi` / `qorechain-diana` first reads the
node's protocol feature switches, `GET {rest}/qorechain/pqc/v1/protocol_features`
(chain v3.2.4 and later): v2 when the listed feature `pqc-sign-bytes-v2`
(`PQC_SIGN_BYTES_V2_FEATURE`) is enabled, v1 when the node lists its features and
that one is disabled or absent. This also covers a fresh network that reuses one
of those chain ids: it enables every feature at genesis and never applies an
upgrade plan. Only when that query cannot answer (an older node, a transport
error, an unexpected or empty payload) does the SDK fall back to the plans.

The plan fallback (the chain's own `SignBytesVersionFor`): for EVERY name in
`SIGN_BYTES_V2_UPGRADES`, ask the node
`GET {rest}/cosmos/upgrade/v1beta1/applied_plan/{name}` and compare the height
**numerically** (it is a string, and `{"height":"0"}` is truthy). If ANY of them
is above 0 → v2; else if the chain is `qorechain-vladi` / `qorechain-diana` → v1;
else → v2. The names are asked in order and the lookup stops at the first
positive height, so mainnet costs one request after its upgrade and the testnet
two. The answer is cached per `(rest_url, chain_id)` for 60 s (a network can
upgrade while an app is running). If neither the features nor the plans can be
read for one of those two networks, the SDK raises `SignBytesVersionError`
instead of guessing.

```python
from qorsdk import (
    build_hybrid_tx, hybrid_sign_and_broadcast, resolve_sign_bytes_version,
    SignBytesResolver, clear_sign_bytes_cache, get_network,
)

# 1. Resolve explicitly, then build (the builders are pure: no network).
TESTNET_REST = get_network("testnet").endpoints.rest
version = resolve_sign_bytes_version("qorechain-diana", rest_url=TESTNET_REST)
built = build_hybrid_tx(..., chain_id="qorechain-diana", sign_bytes_version=version)
built.sign_bytes_version  # "v2"

# 2. Or let the SDK resolve, broadcast, and recover from a stale answer: on a
#    `pqc` code 21 refusal ("hybrid PQC signature verification failed") it
#    re-resolves ONCE, re-signs ONCE, and broadcasts ONCE more.
resp = hybrid_sign_and_broadcast(
    lambda v: build_hybrid_tx(..., chain_id="qorechain-diana", sign_bytes_version=v),
    chain_id="qorechain-diana",
    rest_url=TESTNET_REST,
    sign_bytes_version="auto",   # or "v1" / "v2" to override (no lookup, no retry)
)

# Cache control.
resolve_sign_bytes_version("qorechain-vladi", rest_url=..., force_refresh=True)
clear_sign_bytes_cache()
resolver = SignBytesResolver(ttl=15)  # a private resolver with its own TTL
```

`build_hybrid_tx` and `sign_hybrid_eth` take `sign_bytes_version="v1" | "v2"`.
When it is omitted they use v2 for a chain started on v3.2.0+, and **raise** for
`qorechain-vladi` / `qorechain-diana` (never a silent v1 default). The high-level
paths (`migrate_to_hybrid`, `migrate_pqc_key`, `CrossVmClient` /
`create_cross_vm_client`) take `sign_bytes_version="auto" | "v1" | "v2"` (default
`"auto"`) and use `hybrid_sign_and_broadcast` internally.

The same release changed the **PQC key-migration** and **bridge-attestation**
payloads. Builders for both forms are provided and reproduce the chain's
known-answer vectors byte-for-byte:

- `migration_sign_bytes(version, chain_id, account, from_algorithm_id,
  to_algorithm_id, execution_height, old_public_key, new_public_key)`: v1 is
  the ASCII
  `qorechain-key-migration:chain=…:from=…:to=…:account=…:height=…`; v2 is
  `"qorechain-key-migration-v2"` followed by length-prefixed fields and both
  public keys.
- `bridge_attestation_sign_bytes(version, chain_id, chain, event_type,
  operation_id, tx_hash, amount, asset)`: v1 is the pipe-joined fields with no
  chain-id; v2 is `"qorechain-bridge-attestation-v2"` then `BE64(len f) ‖ f` for
  chain-id and each field.

`is_hybrid_signature_rejection(resp_or_error)` detects the `pqc` code-21 refusal
(code 21 from any other codespace, such as `sdk` "tx too large", does not match).

### Unified eth-native wallet (v0.6.0)

One `eth_secp256k1` key = ONE 20-byte identity rendered three ways - `qor1…`
(bech32), `0x…` (EIP-55), and SVM base58 (the 20 bytes right-padded with 12 zero
bytes to 32). A deposit to any of the three lands in the **same** balance, and the
key spends on **all** lanes. `derive_unified_account` uses the Ethereum HD path
(`m/44'/60'/0'/0/{index}`); `unified_account_from_seed` builds one directly from a
32-byte secret. `addresses_from_20` / `qore_addresses` convert between the three
encodings. The legacy coin-type-118 `derive_native_account` still works (additive).

Native-lane signing over the eth key: `sign_classical_eth` is a classical
secp256k1 signature over `keccak256(SignDoc)` with pubkey type
`/cosmos.evm.crypto.v1.ethsecp256k1.PubKey`; `sign_hybrid_eth` adds the ML-DSA-87
post-quantum signature. Account parsing accepts eth_secp256k1 public keys.

```python
from qorsdk import (
    derive_unified_account, unified_account_from_seed,
    sign_hybrid_eth, resolve_sign_bytes_version,
)

account = derive_unified_account(mnemonic)
account.cosmos  # "qor1…" - QoreChain Native lane
account.evm     # "0x…" - EIP-55 checksummed
account.svm     # "<base58>" - 20 bytes + 12 zero pad

# Sign a QoreChain Native tx from the unified eth key (hybrid PQC path).
built = sign_hybrid_eth(
    account=account,
    chain_id="qorechain-vladi",
    account_number=account_number,
    messages=[msg.cosmos.send(...)],
    fee=fee,
    sequence=sequence,
    sign_bytes_version=resolve_sign_bytes_version(
        "qorechain-vladi", rest_url=get_network("mainnet").endpoints.rest
    ),
)

# A unified account's seed MUST be real secret entropy, and its PQC key needs a
# second, independent secret: a recovery code the user writes down.
import secrets
from qorsdk import generate_pqc_recovery_code, pqc_key_from_recovery_code

code = generate_pqc_recovery_code()  # "QRC1-XXXX-..."; show it to the user once
fresh = unified_account_from_seed(secrets.token_bytes(32), recovery_code=code)
same_key = pqc_key_from_recovery_code(code, fresh.cosmos)  # recover the PQC key later
```

The PQC key of a seed-built account needs a second secret, because the 32-byte
seed is the classical spend key. Pass exactly one keyword argument:

- `recovery_code=` a `QRC1-...` recovery code (`generate_pqc_recovery_code()`,
  checked with `is_valid_recovery_code()`; typing mistakes such as lowercase,
  spaces, O for 0 and I/L for 1 are accepted, a wrong character fails its checksum);
- `pqc_secret=` 32 bytes of independent secret entropy (the same secret a code
  carries: `pqc_recovery_code_from_secret()` encodes it as one, and both give the
  same key; it must not be the seed itself);
- `legacy_seed_derivation=True` the derivation used before 0.13.0, where the PQC
  key follows from the seed alone. Use it only to recover the PQC key of an
  account created before 0.13.0, so you can rotate it (`MsgRotatePQCKey`) to a key
  from a recovery code; never for new accounts.

Calling it with none of these, or more than one, raises `ValueError`. The
mnemonic path (`derive_unified_account`) is unchanged.

`unified_account_from_seed` uses its seed verbatim as the spend key, so the seed
must be a CSPRNG draw or key material the user already keeps secret. Never derive
it from a wallet signature or any other value a third party can ask the wallet
(or the user) to produce - such a value is a bearer secret handed out on request.
Deriving an account from a wallet signature was removed in **v0.8.0**
(`unified_account_from_phantom_signature` now raises); to spend from an existing
external key, register it with `MsgRegisterAuthenticator` and use the
authenticator lanes (`MsgExecuteCosmos` / `MsgExecuteEVM`) below. Any account
previously derived from a signature must be treated as exposed - move its funds.

See the [unified-wallet](https://github.com/qorechain/qorechain-sdk/blob/main/docs/docs/guides/unified-wallet.md) guide.

### Auto-gas, errors, tracking, search

```python
from qorsdk import (
    auto_fee, GasPrice, calculate_fee,        # gas
    decode_tx_error, QoreTxError,             # errors
    wait_for_tx, broadcast_and_wait, with_retry,  # tracking
    get_tx, get_block, search_txs, build_events_query,  # search
)

# Simulate -> gas limit -> x 0.15uqor (DEFAULT_GAS_PRICE; read the chain's
# minimum with fetch_min_gas_price_uqor, opt-in). A hybrid-signed tx on a v3.2.5+ network
# gets ceil(gas_used x 1.02) + 2000 (see "Exact gas" below); otherwise
# ceil(gas_used x 1.4).
fee = auto_fee(client.network.endpoints.rest, built)
calculate_fee(200000, GasPrice.from_string("0.15uqor"))

# A simulation the chain refuses with a registered error raises
# SimulationRefusedError (a QoreTxError and an httpx.HTTPStatusError) naming it,
# e.g. codespace "stakingtier", code 12, kind "stakingtier_nothing_to_claim".
# decode_tx_error(0, None, text) names any text-only refusal the same way.

# Wait for inclusion; raises a typed QoreTxError on a non-zero code.
included = wait_for_tx(client.rest, "TXHASH")

search_txs(client.rest, {"message.sender": native.address}, limit=20, order_by="desc")
```

### Websocket subscriptions

```python
from qorsdk import SubscriptionClient

async def run():
    sub = await SubscriptionClient.connect("http://localhost:26657")
    async def on_block(ev): print("block", ev)
    unsubscribe = await sub.subscribe_new_blocks(on_block)
    await sub.subscribe_tx({"message.sender": native.address}, lambda ev: ...)
    # ... later ...
    await unsubscribe()
    await sub.close()
```

### Utilities

```python
from qorsdk import (
    sha256_hex, keccak256_hex, ripemd160_hex,
    parse_units, format_units,
    is_valid_evm_address, is_valid_svm_address, to_checksum_address,
)

parse_units("1.5", 18)                 # 1500000000000000000
format_units(1500000000000000000, 18)  # "1.5"
to_checksum_address("0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed")
```

### Authenticator lanes (v0.7.0 / chain v3.1.85)

A linked external key - a Phantom **ed25519** key, or a MetaMask **secp256k1**
key bound **by address** - spends from the ONE canonical PQC account through a
**relayer** that submits the tx and pays the fee (its own hybrid-PQC signature
satisfies the ante). The external key **never produces an ML-DSA co-signature**;
its signature over the domain-separated, replay-bound sign-bytes **is** the
authorization, under least-privilege, spending-limit and revocable terms
enforced on-chain.

Three messages carry the lanes, each with a composer:

- `MsgExecuteEVM` (`/qorechain.abstractaccount.v1.MsgExecuteEVM`) -
  `msg.abstractaccount.execute_evm`
- `MsgExecuteCosmos` (`/qorechain.abstractaccount.v1.MsgExecuteCosmos`) -
  `msg.abstractaccount.execute_cosmos`
- `MsgRotatePQCKey` (`/qorechain.pqc.v1.MsgRotatePQCKey`) -
  `msg.pqc.rotate_pqc_key`

The `execute_evm_msg` / `execute_cosmos_msg` / `rotate_pqc_key_msg` builders
compose these from primitives. **Sign-bytes helpers** rebuild the exact digest
the chain re-derives: `evm_auth_sign_bytes` / `cosmos_auth_sign_bytes` (32-byte
SHA-256 digests) and `rotation_sign_bytes` (the domain-separated string both
keys sign).

**NONCE semantics:**

- `MsgExecuteEVM.nonce` = the linked key's **authenticator sequence**: a counter the
  chain keeps in its state for each `(account, linked key)`, starting at 0 and
  incremented by every successful execution. It is **not** the account's EVM
  nonce (`eth_getTransactionCount`). Read it with
  `fetch_auth_nonce(rest, address, pubkey)` (chain v3.2.4, see "Network reads
  added in chain v3.2.4"): 0 for a newly linked key, +1 after each execution the
  chain accepts; abstractaccount code 11 means the value you sent is not the
  chain's.
- `MsgExecuteCosmos.nonce` = the **per-authenticator sequence** for
  `(account, pubkey)`: the same kind of counter, kept per linked key.

**Permission taxonomy & errors.** Fetch the on-chain permission schema with the
gRPC query client's `permission_schema()` (REST equivalent
`GET /qorechain/abstractaccount/v1/permission_schema`) and compare an action to
it before submitting. `decode_tx_error` surfaces the lane failures - codespace
`abstractaccount`: `5` SpendingLimitExceeded, `6` SessionKeyExpired, `10`
PermissionDenied, `11` AuthenticatorReplay; codespace `pqc`: `21`
HybridVerifyFailed.

**Key rotation.** `rotate_pqc_key_msg_from_mnemonic` migrates a legacy
`shake256(mnemonic)` key to the canonical, address-bound key (dual-signs over
`rotation_sign_bytes`); `derive_pqc_legacy` re-derives the old key for the
old-key half.

```python
from qorsdk import (
    evm_auth_sign_bytes, execute_evm_msg,
    rotate_pqc_key_msg_from_mnemonic,
)

# Phantom ed25519 authenticator authorizes an EVM spend from the canonical
# account; the relayer broadcasts and pays. nonce = the account's CURRENT EVM
# nonce (relayer != owner -> no +1).
digest = evm_auth_sign_bytes(
    chain_id="qorechain-diana",
    account="qor1canonical…",
    pubkey=phantom_pubkey,           # 32-byte ed25519 key
    to="0xRecipient…",
    value="1000000000000000000",     # 1 QOR in aqor (wei)
    nonce=current_evm_nonce,
)
signature = phantom_sign(digest)     # your wallet signs the raw 32 bytes
exec_msg = execute_evm_msg(
    relayer="qor1relayer…", account="qor1canonical…", scheme="ed25519",
    pubkey=phantom_pubkey, signature=signature,
    to="0xRecipient…", value="1000000000000000000", nonce=current_evm_nonce,
)

# Migrate a legacy shake256(mnemonic) key to the address-bound key.
build = rotate_pqc_key_msg_from_mnemonic(
    account="qor1canonical…", mnemonic=mnemonic, chain_id="qorechain-diana",
)
```

See the [authenticators](https://docs.qorechain.io/sdk/guides/authenticators) guide.

### EVM authorisation window (v0.8.2 / chain v3.2.0)

From chain v3.2.0 an **EVM-lane transaction is admitted only** from an account
that (a) has a **registered post-quantum key** and (b) has an **open,
unexhausted authorisation window**. The testnet (`qorechain-diana`) enforces this
today; mainnet enforces it from its upgrade height. A plain transfer from an
account with no window is refused with:

```
account qor1… has no open EVM authorisation window; open one with
MsgOpenEVMWindow, signed on the Cosmos lane with the account's post-quantum key
```

Opening a window is an ordinary **Cosmos-lane** message, so it carries the
account's hybrid (classical + ML-DSA-87) signature: the classical key alone can
never open a window. MetaMask and any other EVM client keep working unmodified
*inside* a window.

```python
from qorsdk import (
    RestClient, msg, get_evm_window, describe_evm_window_error,
    MAX_EVM_WINDOW_BLOCKS, MAX_EVM_WINDOW_TXS,
)

# 1. Check what the account has. 200 with found:false when absent - safe to poll.
rest = RestClient(get_network("mainnet").endpoints.rest)
status = get_evm_window(rest, "qor1…")
status.found, status.live          # bool
status.remaining_blocks            # int
status.remaining_txs               # int
status.remaining_value             # int (uqor, exact - never a float)

# 2. Open one. Every field is REQUIRED; the bounds mirror the chain's
#    ValidateBasic and are checked locally, so a bad call raises before it
#    costs a fee.
open_msg = msg.pqc.open_evm_window(
    sender="qor1…",
    blocks=300,             # 1..17280 (MAX_EVM_WINDOW_BLOCKS)
    max_txs=5,              # 1..1000  (MAX_EVM_WINDOW_TXS)
    max_value="2000000",    # > 0, uqor, integer string (cosmos.Int)
)
# …broadcast it through the usual hybrid path (build_hybrid_tx / send_messages).

# 3. Done early? Closing takes effect in the same block.
close_msg = msg.pqc.close_evm_window(sender="qor1…")

# 4. Decode a refusal into a state + remedy. Matches the `pqc` codes (26 no
#    window, 27 exhausted, 28 invalid / no PQC key) AND the chain's text, since
#    over EVM JSON-RPC the refusal arrives as a broadcast error with no codespace.
refusal = describe_evm_window_error(code=26, codespace="pqc", message=err_text)
if refusal:
    refusal.kind      # "no_window" | "window_exhausted" | "invalid_window" | "no_pqc_key"
    refusal.remedy    # what the user must do
```

Opening replaces any existing window rather than adding to it.

**The SDK never opens a window for you.** There is no implicit "open before
send": a window authorises spending, so the step must be explicit and visible to
the user. The SDK gives you the status query, the two composers, the local bounds
check, and the classifier - the wallet decides.

#### Three traps

1. **Ordering - open, then read the nonce, then sign.** QoreChain unifies the
   identity, so the Cosmos sequence **is** the EVM nonce, and
   `MsgOpenEVMWindow` is a Cosmos transaction from the same account: opening a
   window **advances the nonce** (measured on the testnet: 2 before, 3 after). A
   wallet that prepares or signs the EVM transaction first gets `nonce too low`.

2. **`max_value` bounds value *plus* the maximum fee.** It counts the
   transferred value **and** the largest fee each admitted transaction could pay
   (gas limit × gas fee cap), because the holder of the classical key sets the
   gas price and a value-only bound would leave the account drainable through
   fees. Measured on the testnet: a **1,000 uqor** transfer with a 21,000 gas
   limit at 112.5 gwei consumed **3,363 uqor** of the window. Wei→uqor rounds
   **up**, so a series of sub-uqor transfers cannot drain a window that never
   appears to move.

3. **Do not print "about 24 hours" for 17280 blocks.** The chain constant says
   that at 5-second blocks, but **no QoreChain network runs at 5 s**: the testnet
   is at ~1.03 s (17280 blocks ≈ **5 hours**) and mainnet at ~3.1 s (≈ **15
   hours**). Show "up to 17280 blocks", or compute the duration from the chain's
   recent block time.

### Other v3.2.0 behaviour worth knowing

Nothing to call in the SDK, but these change when an existing call is refused:

- **`msg.rdk.submit_batch` - settle only as the rollup's sequencer.** From
  v3.2.0 `MsgSubmitBatch` is accepted **only** from the rollup's
  `SequencerConfig.SequencerAddress`, falling back to `Creator` when no sequencer
  is set; anyone else gets `ErrUnauthorized`
  (`"%s may not settle batches for rollup %s"`). Batches must also **extend the
  chain by index** and cannot overwrite an existing one. `msg.rdk.pause_rollup`,
  `msg.rdk.resume_rollup` and `msg.rdk.stop_rollup` now require the **creator**.

- **`x/ai` enforces its per-sender rate limit.** The limit was declared but never
  enforced; from v3.2.0 it is. The window is **30 BLOCKS**, not a minute, despite
  the field being named `max_tx_per_minute` (~31 s on the testnet, ~93 s on
  mainnet). A network born on this binary starts at the genesis default **10**;
  the upgrade handler raises an upgraded chain to **600**, and no message can
  change it on a running chain. **Read it** via `qorechain.ai.v1.Query/Config` -
  never assume either value. Batch senders (faucets, relayers, exchange hot
  wallets) that exceed it get `ai` `ErrTxRejected`.

### Staking tiers (v0.10.0, chain v3.2.4)

Lock part of an existing delegation for 3, 6 or 12 months for a bonus on top
of the staking reward. Running a light node or a validator adds to it, up to a
total cap; leaving early burns a penalty and forfeits the bonus. The terms are
governance parameters: read them rather than hard-coding them.

```python
from qorsdk import RestClient, get_network, msg, fetch_staking_tier_params, fetch_staking_locks

rest = RestClient(get_network("mainnet").endpoints.rest)
params = fetch_staking_tier_params(rest)
# params.lock_tiers -> (StakingLockTier(months=3, bonus_bps=150), StakingLockTier(months=6, ...), ...)

lock = msg.stakingtier.lock_delegation(
    delegator=delegator, validator=validator, amount="10000000", months=3
)
# …broadcast it through the usual hybrid path (build_hybrid_tx / send_messages).

locks = fetch_staking_locks(rest, delegator)  # locks.locks, locks.claimable
claim = msg.stakingtier.claim_bonus(holder=delegator)
unlock = msg.stakingtier.unlock_early(delegator=delegator, lock_id=locks.locks[0].id)
```

`lock_delegation` raises `ValueError`, before anything is signed, on a term
other than 3, 6 or 12 (`STAKING_LOCK_MONTHS`) and on an amount that is not a
positive integer in base units. A locked delegation cannot be undelegated or
redelegated until the lock ends (`stakingtier` code 13, kind
`stakingtier_stake_locked`). `fetch_staking_tier_pool(rest)` reads the bonus
pool; every read has an `_async` twin.

### Network reads added in chain v3.2.4

```python
from qorsdk import (
    RestClient, fetch_auth_nonce, fetch_protocol_features,
    is_protocol_feature_enabled, fetch_pqc_status, get_network,
)

rest = RestClient(get_network("mainnet").endpoints.rest)

# The nonce a linked authenticator key must sign next (MsgExecuteEVM / MsgExecuteCosmos).
n = fetch_auth_nonce(rest, address, pubkey)  # n.nonce, n.linked

# Which consensus rules the network enforces today, by name.
on = is_protocol_feature_enabled(rest, "pqc-sign-bytes-v2")
features = fetch_protocol_features(rest)  # features.features, features.height

# Whether the account's PQC key was proven by a proof of possession.
proven = fetch_pqc_status(get_network("mainnet").endpoints.rest, address).get("possession_proven")
```

### Chain v3.2.5 (v0.12.0)

Mainnet applied v3.2.5 at height 3,906,833; the testnet runs v3.2.6.

#### Exact gas for hybrid transactions

From v3.2.5 the fee simulation charges the post-quantum signature check, so its
result is exact up to small variance. For a hybrid-signed transaction on a
network that has applied `v3.2.5`, `estimate_gas` / `auto_fee` use
`exact_hybrid_gas(gas_used)` = `ceil(gas_used x 1.02) + 2000`
(`EXACT_GAS_MULTIPLIER`, `EXACT_GAS_HEADROOM`; once per transaction, not per
signer). A native-lane transaction pays its whole gas limit times the gas
price, so the tighter limit is a lower fee. Classical transactions, networks
below v3.2.5 and a node that cannot be asked keep `ceil(gas_used x 1.4)`. An
explicit `gas_multiplier` always gives `ceil(gas_used x gas_multiplier)`. The
plan lookup is cached per REST URL.

#### KEM key registry

An account can publish one ML-KEM-1024 (FIPS 203) public key so that anyone
can encrypt to it. The chain stores and serves the raw key; the encryption is
not part of this SDK.

```python
from qorsdk import RestClient, fetch_kem_key, get_network, msg

register = msg.pqc.register_kem_key(sender=address, public_key=kem_public_key)  # 1568 bytes
remove = msg.pqc.remove_kem_key(sender=address)
# Both always need the hybrid signature (build_hybrid_tx).

got = fetch_kem_key(RestClient(get_network("mainnet").endpoints.rest), address)  # bech32 or 0x
# got.found, got.key.public_key, got.key.algorithm_id (2), got.key.registered_height
```

- One key per account; registering again replaces it (`replaced` in the
  response). No proof of possession: the hybrid signature authenticates it,
  and the account needs a registered post-quantum signature key.
- `register_kem_key` checks the key before anything is signed: 1568 bytes,
  every coefficient below 3329 (the FIPS 203 modulus check), not all zero.
- Refusals are named: `pqc` 250 (registry not enabled), 251 (invalid key), 252
  (nothing to remove), 253 (the same key is already published), 254 (no
  post-quantum signature key).

#### Spending rules, governance messages and new reads

- `update_spending_rules` also checks EVM token denoms the way v3.2.5 does when
  a rule is saved: an `erc20/`, `erc721/` or `erc1155/` denom carries a
  `0x`-prefixed 20-byte contract address, and an `erc20/` denom is the address
  alone (`validate_evm_denom`). The chain refuses such a rule with
  `abstractaccount` code 8 (`invalid_spending_rule`).
- `fetch_spending_rules(rest, address)` and `fetch_authenticators(rest,
  address)` read what an account stored and which keys it linked.
- Governance-only composers: `msg.abstractaccount.update_config`,
  `msg.crossvm.update_params` (with the EVM bridge allowlist,
  `"cosmwasm:<contract>"` entries) and `msg.rdk.update_params`, each checked
  against the chain's bounds before a proposal is built. From chain v3.2.8 they
  require every field; see "Chain v3.2.8" below.

### Chain v3.2.8

#### Linking a key: possession proof and spending rule

`MsgRegisterAuthenticator` carries `possession_proof` (field 8), required from
v3.2.8: a signature BY THE KEY BEING LINKED over the link message.
`msg.abstractaccount.register_authenticator` refuses an empty proof.

```python
from qorsdk import (
    authenticator_link_message, link_proof_ed25519, link_proof_secp256k1,
    link_proof_eth, link_authenticator_msgs,
)

# A browser wallet signs this text itself (Phantom signMessage, MetaMask
# personal_sign). Five lines: domain, chain, account, scheme, lowercase hex key.
text = authenticator_link_message("qorechain-diana", owner, "ed25519", phantom_pubkey)

# With the private key in hand:
proof = link_proof_ed25519(seed32, chain_id="qorechain-diana", account_address=owner)
# link_proof_secp256k1: 33-byte compressed key, 64-byte r||s over sha256(text)
# link_proof_eth: 20-byte Ethereum address, EIP-191 personal_sign (65 bytes)

# A key with send / evm / deploy / svm / all needs an enabled spending rule on
# the ACCOUNT that bounds every denom (the chain applies the FIRST enabled
# rule). Send both messages, owner-signed, in ONE transaction:
msgs = link_authenticator_msgs(
    owner=owner, chain_id="qorechain-diana",
    scheme=proof.scheme, pubkey=proof.pubkey, possession_proof=proof.possession_proof,
    permissions=["send"], expiry_unix=expiry, label="phantom",
    spending_rule={"id": "default", "enabled": True, "per_tx_limit": 1_000_000},
)  # -> [MsgUpdateSpendingRules, MsgRegisterAuthenticator]
```

`MsgUpdateSpendingRules` REPLACES the account's rules wholesale: pass every rule
the account should keep. It may be sent for an account that does not exist yet
when `account_address == owner` (it creates the account).

#### Execution results

A failed `MsgExecuteEVM` / `MsgExecuteCosmos` that was authorised now returns
`success=false` inside a transaction with code 0, emits
`abstractaccount_execution_failed` and consumes the nonce.
`decode_execution_results(included)` returns one `ExecutionResult` per execute
message (`success`, `ret`, `gas_used`, `vm_error`, `reason`);
`require_executions_succeeded(included)` raises `ExecutionFailedError` when any
failed.

#### Governance params: every field, copied from the chain

crossvm, svm and rdk `MsgUpdateParams` replace the parameters wholesale, so the
composers refuse a missing field (a field left out would be zero: crossvm
`bridge_target_pins` wiped, svm custody ceilings removed). svm also refuses
`enabled=True` with `max_custody_hard_uqor == 0`. Build a proposal from the
values in force:

```python
from qorsdk import crossvm_update_params_from_current, svm_update_params_from_current

m = crossvm_update_params_from_current(rest, authority=gov, changes={"max_pending_per_sender": 50})
# svm: nodes without /qorechain/svm/v1/params take current=<every SVMParams field>
s = svm_update_params_from_current(rest, authority=gov, changes={"max_custody_hard_uqor": 10**12})
```

`rdk_update_params_from_current` works the same way.

#### Cross-VM

- Async calls into CosmWasm take `async_gas_limit` (0 = 500,000; else
  250,000..10,000,000) and `async_max_factor` (millionths, 1,000,000 = 1x; 0 =
  four times the factor at submission); both are refused on synchronous calls
  and other targets. The call holds an escrow (`async_gas_limit x factor x gas
  price`, about 0.2 QOR by default) refunded when it finishes, pays a queue-slot
  fee, and a sender may have at most 100 pending calls.
- The pending query is paginated (at most 100 per page):
  `q.crossvm.all_pending_messages()` follows `next_key`. `payload_hex` in the
  list is cut to 1,024 bytes; read the full payload with `q.crossvm.message(id)`.
- `CrossVmClient(fee="auto")` simulates each transaction instead of using a
  fixed fee.

#### EVM window scope

`msg.pqc.open_evm_window` takes `validators` (0x contract addresses),
`staking_validators` (`qorvaloper...`) and `ibc_receivers`
(`"channel-0/cosmos1..."`). Standard precompile methods are deny-by-default
through a window: staking delegate / redelegate need `staking_validators`,
ICS-20 needs `ibc_receivers`; undelegate, vote and withdraw-address changes are
refused through the window (use a PQC-signed Cosmos transaction). Rotating,
migrating or re-registering the PQC key closes the window.

#### Gas

- EVM transactions above the EVM gas cap are refused (30,000,000 by default):
  `fetch_evm_limits(rest)` reads `/qorechain/pqc/v1/evm_limits`,
  `check_evm_gas_limit(gas, cap=...)` refuses before signing, and
  `execute_evm_msg` checks its `gas_limit`.
- A Cosmos transaction above 50,000,000 gas is refused before signing.
- Use auto / simulation for wasm and cross-VM gas: the first call of a contract
  code in a block costs much more (a cw20 transfer about 533k gas, repeats about
  84k). `estimate_fee(..., messages=msgs)` refuses its fixed 200,000 fallback for
  a tx with a CosmWasm execute / instantiate / migrate or `MsgCrossVMCall`, and
  simulation sizes such a tx at least `ceil(gas_used x 1.3)`.
- Minimum gas price (opt-in, no default path calls it):
  `fetch_min_gas_price_uqor(rest)` reads `/cosmos/evm/feemarket/v1/params` and
  returns `max(min_gas_price / 10^12, 0.1)` uqor per gas as an exact `Decimal`;
  `recommended_gas_price_uqor(rest, margin="1.5")` returns `max(0.15, that x
  margin)`. The default gas price stays `0.15uqor`.

## Regenerating protobuf code (maintainers)

The generated protobuf modules under `src/qorechain/proto/` are committed, so
users never run `protoc`. To regenerate after a proto change (requires `buf`):

```bash
bash scripts/codegen-py.sh
```

It runs `buf generate` (public-registry `protocolbuffers/python` + `pyi`
plugins, pinned to the protobuf 5.29.x line), rewrites dependency imports to
`cosmpy`'s bundled protos so the gencode shares one descriptor pool, and writes
package `__init__.py` files.

## Out of scope (use a dedicated library)

Browser-wallet adapters (Keplr / MetaMask / Phantom) and viem / `@solana/web3.js`
-style EVM/SVM clients are intentionally **not** part of this SDK - they are
JS/browser-specific. In Python, talk to the EVM with [web3.py](https://web3py.readthedocs.io)
and to the SVM with [solana-py](https://michaelhly.github.io/solana-py/), pointing
them at the network's `evm_rpc` / `svm_rpc` endpoints. This SDK covers the native
Native chain surface end to end.

## Development

```bash
python -m venv .venv
.venv/bin/pip install -e "packages/py[dev]"
.venv/bin/pytest packages/py
.venv/bin/mypy packages/py/src
.venv/bin/ruff check packages/py/src packages/py/tests
```

## License

Apache-2.0
