omne-sdk 0.1.0__tar.gz

omne_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python build + cache artifacts — never committed.
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

omne_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: omne-sdk
+Version: 0.1.0
+Summary: Omne Python SDK — post-quantum (ML-DSA-44) wallet, ABI, and JSON-RPC client
+Author: OmneDAO
+License: Apache-2.0
+Keywords: blockchain,fips-204,ml-dsa,omne,post-quantum
+Requires-Python: >=3.10
+Requires-Dist: dilithium-py==1.4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Omne Python SDK (`omne-sdk`)
+
+Post-quantum Python SDK for the Omne L1 — ML-DSA-44 (FIPS 204) wallet, ABI
+encoding, and JSON-RPC client. Parity-matched with the
+[TypeScript SDK](../typescript): the same mnemonic produces the same `om1z`
+addresses, and Python-produced signatures are accepted by the node's verify
+path.
+
+> **Status:** validated. Offline crypto/address parity is covered by
+> `tests/test_parity.py` (6/6). Validated against a live 4-validator mesh on
+> 2026-06-17: a Python account (parity-matched, genesis-funded address) built →
+> ML-DSA-44 signed → submitted `mint_permission` to the live `cinchor_permissions`
+> contract; the node accepted the Python signature and the reference-typed
+> `get_principal` return decoded back to the principal address. See
+> [`examples/live_mint.py`](examples/live_mint.py).
+
+> **Calling pysub contracts:** the ABI method name is the contract-qualified
+> selector `"<contract>::<method>"` (e.g. `cinchor_permissions::get_status`).
+> The SDK passes the selector through verbatim — qualify it at the call site.
+> Reference (address/bytes) returns come back as a `0x`-hex `returnValue`;
+> decode addresses with `to_omne_address(bytes.fromhex(rv[2:]))`.
+
+## Install
+
+```bash
+pip install -e ".[dev]"   # from sdk/python/
+```
+
+The only runtime dependency is [`dilithium-py`](https://pypi.org/project/dilithium-py/)
+(pure-Python FIPS 204), **pinned exact (`==1.4.0`)**. Its public `key_derive(ξ)`
+is byte-identical to the TS SDK's `@noble/post-quantum` `ml_dsa44.keygen(seed)`
+— verified across multiple seeds, which is why addresses match. Because keygen
+output determines `om1z` addresses, the pin is load-bearing: re-run the parity
+tests before bumping it. Everything else (BIP39, the HD KDF, bech32m, the tx
+hash, the ABI codec) is stdlib.
+
+## Quickstart
+
+```python
+from omne_sdk import Wallet, OmneClient, AbiEncode
+
+wallet  = Wallet.from_mnemonic("abandon abandon ... about")
+account = wallet.get_account(0)
+print(account.address)            # om1z…
+
+client = OmneClient("http://127.0.0.1:26657", chain_id=3)
+
+# read-only query (reference-typed returns come back as 0x-hex)
+res = client.query_contract(
+    "om1z<contract>", "get_principal",
+    [AbiEncode.address("om1z<capabilityId>")],
+)
+
+# state-modifying call: build → sign (ML-DSA-44) → submit
+tx_hash = client.send_contract_call(
+    account, "om1z<contract>", "mint_permission",
+    [AbiEncode.address("om1z<id>"), AbiEncode.u128(100)],
+)
+receipt = client.wait_for_receipt(tx_hash)
+```
+
+## Layout
+
+| Module | Mirrors (TS) | Responsibility |
+|---|---|---|
+| `address.py` | `utils.ts` | bech32m `om1z` codec, `derive_address_from_public_key`, hex |
+| `wallet.py` | `wallet.ts` | BIP39 + hardened HMAC-SHA512 HD KDF, ML-DSA-44 keygen/sign |
+| `transaction.py` | `wallet.ts` (hash) | tx build + canonical **little-endian** signing preimage |
+| `abi.py` | `contract.ts` | `ArgType` / `AbiEncode` / `encode_contract_call` (**big-endian** wire) |
+| `rpc.py` | `client.ts` | JSON-RPC: `omne_sendTransaction` wire, `omne_call`, nonce, receipt |
+
+## Parity vectors
+
+`tests/test_parity.py` pins:
+- ML-DSA-44 keygen public-key SHA-256 for fixed seeds (vs `@noble`),
+- mnemonic → HD seed → pubkey → `om1z` address for the canonical BIP39 test
+  mnemonic,
+- address bech32m round-trip, sign→verify, and ABI call shape.
+
+Run: `pytest -q` (offline; no node required).
+
+## Notes / follow-ups
+- BIP39 mnemonic **checksum validation** against the English wordlist is a
+  follow-up; seed derivation (the parity-critical path) is exact.
+- `dilithium-py` is pure-Python (keygen ~8 ms, sign ~46 ms). Fine for a client
+  SDK; a native backend (liboqs/PQClean) is a drop-in optimization behind the
+  same keygen/sign interface if high-throughput signing is ever needed.

omne_sdk-0.1.0/README.md

@@ -0,0 +1,87 @@
+# Omne Python SDK (`omne-sdk`)
+
+Post-quantum Python SDK for the Omne L1 — ML-DSA-44 (FIPS 204) wallet, ABI
+encoding, and JSON-RPC client. Parity-matched with the
+[TypeScript SDK](../typescript): the same mnemonic produces the same `om1z`
+addresses, and Python-produced signatures are accepted by the node's verify
+path.
+
+> **Status:** validated. Offline crypto/address parity is covered by
+> `tests/test_parity.py` (6/6). Validated against a live 4-validator mesh on
+> 2026-06-17: a Python account (parity-matched, genesis-funded address) built →
+> ML-DSA-44 signed → submitted `mint_permission` to the live `cinchor_permissions`
+> contract; the node accepted the Python signature and the reference-typed
+> `get_principal` return decoded back to the principal address. See
+> [`examples/live_mint.py`](examples/live_mint.py).
+
+> **Calling pysub contracts:** the ABI method name is the contract-qualified
+> selector `"<contract>::<method>"` (e.g. `cinchor_permissions::get_status`).
+> The SDK passes the selector through verbatim — qualify it at the call site.
+> Reference (address/bytes) returns come back as a `0x`-hex `returnValue`;
+> decode addresses with `to_omne_address(bytes.fromhex(rv[2:]))`.
+
+## Install
+
+```bash
+pip install -e ".[dev]"   # from sdk/python/
+```
+
+The only runtime dependency is [`dilithium-py`](https://pypi.org/project/dilithium-py/)
+(pure-Python FIPS 204), **pinned exact (`==1.4.0`)**. Its public `key_derive(ξ)`
+is byte-identical to the TS SDK's `@noble/post-quantum` `ml_dsa44.keygen(seed)`
+— verified across multiple seeds, which is why addresses match. Because keygen
+output determines `om1z` addresses, the pin is load-bearing: re-run the parity
+tests before bumping it. Everything else (BIP39, the HD KDF, bech32m, the tx
+hash, the ABI codec) is stdlib.
+
+## Quickstart
+
+```python
+from omne_sdk import Wallet, OmneClient, AbiEncode
+
+wallet  = Wallet.from_mnemonic("abandon abandon ... about")
+account = wallet.get_account(0)
+print(account.address)            # om1z…
+
+client = OmneClient("http://127.0.0.1:26657", chain_id=3)
+
+# read-only query (reference-typed returns come back as 0x-hex)
+res = client.query_contract(
+    "om1z<contract>", "get_principal",
+    [AbiEncode.address("om1z<capabilityId>")],
+)
+
+# state-modifying call: build → sign (ML-DSA-44) → submit
+tx_hash = client.send_contract_call(
+    account, "om1z<contract>", "mint_permission",
+    [AbiEncode.address("om1z<id>"), AbiEncode.u128(100)],
+)
+receipt = client.wait_for_receipt(tx_hash)
+```
+
+## Layout
+
+| Module | Mirrors (TS) | Responsibility |
+|---|---|---|
+| `address.py` | `utils.ts` | bech32m `om1z` codec, `derive_address_from_public_key`, hex |
+| `wallet.py` | `wallet.ts` | BIP39 + hardened HMAC-SHA512 HD KDF, ML-DSA-44 keygen/sign |
+| `transaction.py` | `wallet.ts` (hash) | tx build + canonical **little-endian** signing preimage |
+| `abi.py` | `contract.ts` | `ArgType` / `AbiEncode` / `encode_contract_call` (**big-endian** wire) |
+| `rpc.py` | `client.ts` | JSON-RPC: `omne_sendTransaction` wire, `omne_call`, nonce, receipt |
+
+## Parity vectors
+
+`tests/test_parity.py` pins:
+- ML-DSA-44 keygen public-key SHA-256 for fixed seeds (vs `@noble`),
+- mnemonic → HD seed → pubkey → `om1z` address for the canonical BIP39 test
+  mnemonic,
+- address bech32m round-trip, sign→verify, and ABI call shape.
+
+Run: `pytest -q` (offline; no node required).
+
+## Notes / follow-ups
+- BIP39 mnemonic **checksum validation** against the English wordlist is a
+  follow-up; seed derivation (the parity-critical path) is exact.
+- `dilithium-py` is pure-Python (keygen ~8 ms, sign ~46 ms). Fine for a client
+  SDK; a native backend (liboqs/PQClean) is a drop-in optimization behind the
+  same keygen/sign interface if high-throughput signing is ever needed.

omne_sdk-0.1.0/examples/live_mint.py

@@ -0,0 +1,111 @@
+"""Live-mesh integration proof for the Omne Python SDK.
+
+A Python-derived account (same demo mnemonic as the TS smoke -> parity-matched,
+genesis-funded address) builds -> ML-DSA-44 signs -> submits a mint_permission
+call to the live cinchor_permissions contract, then reads it back. Proves the
+node accepts a Python signature and reference returns decode in Python.
+
+  python live_mint.py <rpc_url> <contract_address> <wallets_json>
+"""
+
+import hashlib
+import json
+import sys
+import time
+
+from omne_sdk import Wallet, OmneClient, AbiEncode
+from omne_sdk.address import from_omne_address, to_omne_address
+
+RPC = sys.argv[1]
+CONTRACT = sys.argv[2]
+WALLETS = sys.argv[3]
+CHAIN_ID = 3
+# pysub contracts export contract-qualified selectors; the ABI method name is
+# "<contract>::<method>" (the @omne SDK passes the selector through verbatim).
+SEL = "cinchor_permissions::"
+
+
+def derive_capability_id(principal: str, agent: str, nonce: int, created_at: int) -> str:
+    pre = (
+        from_omne_address(principal)
+        + from_omne_address(agent)
+        + nonce.to_bytes(8, "big")
+        + created_at.to_bytes(8, "big")
+    )
+    return to_omne_address(hashlib.sha256(pre).digest())
+
+
+def decode_ref(rv) -> str:
+    """A reference (address) return comes back as 0x-hex; decode to om1z."""
+    if isinstance(rv, str) and rv.startswith("0x"):
+        return to_omne_address(bytes.fromhex(rv[2:]))
+    return str(rv)
+
+
+def main() -> int:
+    w = json.load(open(WALLETS))
+    principal = Wallet.from_mnemonic(w["principal"]["mnemonic"]).get_account(0)
+    agent = Wallet.from_mnemonic(w["agent"]["mnemonic"]).get_account(0)
+    client = OmneClient(RPC, CHAIN_ID)
+    print(f"principal: {principal.address}")
+    print(f"agent:     {agent.address}")
+
+    # wait until the freshly-deployed contract is callable on this node
+    probe = AbiEncode.address(principal.address)
+    for _ in range(24):
+        try:
+            client.query_contract(CONTRACT, SEL + "get_status", [probe])
+            break
+        except Exception:
+            time.sleep(3)
+    else:
+        print("FAIL: contract not callable")
+        return 1
+
+    now = int(time.time())
+    cap = derive_capability_id(principal.address, agent.address, 777, now)
+    print(f"capabilityId: {cap}")
+
+    # build -> ML-DSA-44 sign -> submit (the node verifies the Python signature)
+    tx = client.send_contract_call(
+        principal,
+        CONTRACT,
+        SEL + "mint_permission",
+        [
+            AbiEncode.address(cap),
+            AbiEncode.address(principal.address),
+            AbiEncode.address(agent.address),
+            AbiEncode.u128(100),          # max_spend
+            AbiEncode.u128(now + 3600),   # valid_until
+            AbiEncode.u128(0),            # allowlist_enabled
+            AbiEncode.u128(now),          # current_time
+        ],
+    )
+    print(f"mint tx: {tx}")
+    client.wait_for_receipt(tx, timeout=60)
+
+    # assert the capability is active
+    status = None
+    for _ in range(15):
+        status = client.query_contract(CONTRACT, SEL + "get_status", [AbiEncode.address(cap)]).get("returnValue")
+        if str(status) == "1":
+            print("PASS: get_status == 1 (active) — node accepted the Python-signed mint")
+            break
+        time.sleep(2)
+    else:
+        print(f"FAIL: get_status not active (got {status!r})")
+        return 1
+
+    # full reference-return path in Python: get_principal should decode to the principal
+    rv = client.query_contract(CONTRACT, SEL + "get_principal", [AbiEncode.address(cap)]).get("returnValue")
+    got = decode_ref(rv)
+    print(f"get_principal returnValue={rv!r} -> {got}")
+    if got == principal.address:
+        print("PASS: get_principal decodes to the principal address (reference-return path)")
+        return 0
+    print("FAIL: get_principal mismatch")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

omne_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "omne-sdk"
+version = "0.1.0"
+description = "Omne Python SDK — post-quantum (ML-DSA-44) wallet, ABI, and JSON-RPC client"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "OmneDAO" }]
+keywords = ["omne", "blockchain", "post-quantum", "ml-dsa", "fips-204"]
+dependencies = [
+    # FIPS 204 ML-DSA-44. key_derive(xi) is byte-identical to the TS SDK's
+    # @noble/post-quantum ml_dsa44.keygen(seed) (parity-verified on 1.4.0).
+    # PINNED EXACT: keygen output determines om1z addresses, so an upstream
+    # release must not silently change it — re-verify parity before bumping.
+    "dilithium-py==1.4.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/omne_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

omne_sdk-0.1.0/src/omne_sdk/__init__.py

@@ -0,0 +1,42 @@
+"""Omne Python SDK — post-quantum (ML-DSA-44) wallet, ABI, and RPC client.
+
+Parity-matched with the TypeScript SDK (sdk/typescript): the same mnemonic
+yields the same om1z addresses, and Python-produced signatures are accepted by
+the node's verify path. See tests/test_parity.py for the proof vectors.
+"""
+
+from .address import (
+    derive_address_from_public_key,
+    from_omne_address,
+    parse_address,
+    to_omne_address,
+)
+from .abi import AbiArgument, AbiEncode, ArgType, encode_contract_call
+from .errors import OmneError, RpcError, ValidationError, WalletError
+from .rpc import OmneClient
+from .transaction import build_transaction, hash_transaction
+from .wallet import Wallet, WalletAccount, mnemonic_to_seed
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Wallet",
+    "WalletAccount",
+    "mnemonic_to_seed",
+    "OmneClient",
+    "AbiEncode",
+    "AbiArgument",
+    "ArgType",
+    "encode_contract_call",
+    "build_transaction",
+    "hash_transaction",
+    "to_omne_address",
+    "from_omne_address",
+    "parse_address",
+    "derive_address_from_public_key",
+    "OmneError",
+    "WalletError",
+    "ValidationError",
+    "RpcError",
+    "__version__",
+]

omne_sdk-0.1.0/src/omne_sdk/abi.py

@@ -0,0 +1,113 @@
+"""Omne ABI wire encoding for contract calls.
+
+Port of sdk/typescript/src/contract.ts. Encodes a method call into the binary
+wire format the runtime decodes, placed (hex-encoded) in a transaction's `data`
+field or an omne_call `data` field:
+
+    MAGIC "OMNE" (4) | VERSION 0x01 (1) | method_len u16 BE | method_utf8
+        | arg_count u16 BE | [ type u8 | data_len u32 BE | data ]*
+
+NOTE: ABI integers are BIG-endian here (the codec), distinct from the
+LITTLE-endian transaction-hash preimage in transaction.py. Keep them separate.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import IntEnum
+
+from .address import parse_address
+
+_ABI_MAGIC = b"OMNE"
+_ABI_VERSION = 0x01
+_MAX_METHOD_NAME_LEN = 256
+_MAX_ARG_COUNT = 64
+
+
+class ArgType(IntEnum):
+    U32 = 0x01
+    U64 = 0x02
+    I32 = 0x03
+    I64 = 0x04
+    STRING = 0x05
+    BYTES = 0x06
+    BOOL = 0x07
+    ADDRESS = 0x08
+    U128 = 0x09
+
+
+@dataclass(frozen=True)
+class AbiArgument:
+    type: ArgType
+    data: bytes
+
+
+class AbiEncode:
+    """Convenience builders for typed ABI arguments (big-endian numerics)."""
+
+    @staticmethod
+    def u32(value: int) -> AbiArgument:
+        return AbiArgument(ArgType.U32, int(value).to_bytes(4, "big"))
+
+    @staticmethod
+    def u64(value: int) -> AbiArgument:
+        return AbiArgument(ArgType.U64, int(value).to_bytes(8, "big"))
+
+    @staticmethod
+    def i32(value: int) -> AbiArgument:
+        return AbiArgument(ArgType.I32, int(value).to_bytes(4, "big", signed=True))
+
+    @staticmethod
+    def i64(value: int) -> AbiArgument:
+        return AbiArgument(ArgType.I64, int(value).to_bytes(8, "big", signed=True))
+
+    @staticmethod
+    def u128(value: int) -> AbiArgument:
+        return AbiArgument(ArgType.U128, int(value).to_bytes(16, "big"))
+
+    @staticmethod
+    def string(value: str) -> AbiArgument:
+        return AbiArgument(ArgType.STRING, value.encode("utf-8"))
+
+    @staticmethod
+    def bytes_(value: bytes) -> AbiArgument:
+        return AbiArgument(ArgType.BYTES, bytes(value))
+
+    @staticmethod
+    def bool_(value: bool) -> AbiArgument:
+        return AbiArgument(ArgType.BOOL, b"\x01" if value else b"\x00")
+
+    @staticmethod
+    def address(omne_address: str) -> AbiArgument:
+        payload = parse_address(omne_address)
+        if len(payload) != 32:
+            raise ValueError(f"Address must be 32 bytes, got {len(payload)}")
+        return AbiArgument(ArgType.ADDRESS, payload)
+
+    @staticmethod
+    def address_bytes(payload: bytes) -> AbiArgument:
+        if len(payload) != 32:
+            raise ValueError(f"Address must be 32 bytes, got {len(payload)}")
+        return AbiArgument(ArgType.ADDRESS, bytes(payload))
+
+
+def encode_contract_call(method: str, args: list[AbiArgument] | None = None) -> str:
+    """Encode a method call into the Omne ABI wire format; returns bare hex."""
+    args = args or []
+    method_bytes = method.encode("utf-8")
+    if len(method_bytes) > _MAX_METHOD_NAME_LEN:
+        raise ValueError(f"Method name exceeds {_MAX_METHOD_NAME_LEN} byte limit")
+    if len(args) > _MAX_ARG_COUNT:
+        raise ValueError(f"Argument count {len(args)} exceeds maximum of {_MAX_ARG_COUNT}")
+
+    out = bytearray()
+    out += _ABI_MAGIC
+    out.append(_ABI_VERSION)
+    out += len(method_bytes).to_bytes(2, "big")
+    out += method_bytes
+    out += len(args).to_bytes(2, "big")
+    for arg in args:
+        out.append(int(arg.type))
+        out += len(arg.data).to_bytes(4, "big")
+        out += arg.data
+    return out.hex()

omne_sdk-0.1.0/src/omne_sdk/address.py

@@ -0,0 +1,129 @@
+"""Omne address + identifier encoding.
+
+The Omne chain is uniformly 32-byte (post-quantum). Addresses are bech32m
+encodings of a 32-byte payload under witness version 2 (``om1z…``), matching
+the TypeScript SDK (sdk/typescript/src/utils.ts) and the Rust-side
+``PqcAccountAddress`` exactly:
+
+    address = bech32m("om", [2, ...toWords(SHA-256("OMNE_PQC_ADDRESS_V1" || pubkey))])
+
+This module is pure stdlib (hashlib) + an inline bech32m (BIP-350). Every
+function here is parity-verified against the TS SDK ground truth (see
+tests/test_parity.py).
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+ADDRESS_HRP = "om"
+ADDRESS_WITNESS_VERSION = 2  # bech32 alphabet index 2 = 'z' -> "om1z…"
+ADDRESS_DOMAIN_TAG = b"OMNE_PQC_ADDRESS_V1"
+ADDRESS_PAYLOAD_BYTES = 32
+
+_CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l"
+_CHARSET_REV = {c: i for i, c in enumerate(_CHARSET)}
+_BECH32M_CONST = 0x2BC830A3
+
+
+# ── hex helpers ─────────────────────────────────────────────────────
+def to_hex(data: bytes) -> str:
+    return data.hex()
+
+
+def from_hex(value: str) -> bytes:
+    return bytes.fromhex(value[2:] if value.startswith("0x") else value)
+
+
+# ── bech32m (BIP-350) ───────────────────────────────────────────────
+def _polymod(values: list[int]) -> int:
+    gen = [0x3B6A57B2, 0x26508E6D, 0x1EA119FA, 0x3D4233DD, 0x2A1462B3]
+    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: str) -> list[int]:
+    return [ord(c) >> 5 for c in hrp] + [0] + [ord(c) & 31 for c in hrp]
+
+
+def _create_checksum(hrp: str, data: list[int]) -> list[int]:
+    values = _hrp_expand(hrp) + data
+    polymod = _polymod(values + [0] * 6) ^ _BECH32M_CONST
+    return [(polymod >> 5 * (5 - i)) & 31 for i in range(6)]
+
+
+def _verify_checksum(hrp: str, data: list[int]) -> bool:
+    return _polymod(_hrp_expand(hrp) + data) == _BECH32M_CONST
+
+
+def _convert_bits(data: list[int], from_bits: int, to_bits: int, pad: bool) -> list[int]:
+    acc = 0
+    bits = 0
+    out: list[int] = []
+    maxv = (1 << to_bits) - 1
+    for value in data:
+        if value < 0 or value >> from_bits:
+            raise ValueError("invalid value in convert_bits")
+        acc = (acc << from_bits) | value
+        bits += from_bits
+        while bits >= to_bits:
+            bits -= to_bits
+            out.append((acc >> bits) & maxv)
+    if pad:
+        if bits:
+            out.append((acc << (to_bits - bits)) & maxv)
+    elif bits >= from_bits or ((acc << (to_bits - bits)) & maxv):
+        raise ValueError("invalid padding in convert_bits")
+    return out
+
+
+# ── om1z address codec ──────────────────────────────────────────────
+def to_omne_address(address_bytes: bytes) -> str:
+    """Encode a 32-byte payload as a canonical ``om1z…`` bech32m address."""
+    if len(address_bytes) != ADDRESS_PAYLOAD_BYTES:
+        raise ValueError(f"Address must be {ADDRESS_PAYLOAD_BYTES} bytes, got {len(address_bytes)}")
+    data = [ADDRESS_WITNESS_VERSION] + _convert_bits(list(address_bytes), 8, 5, True)
+    combined = data + _create_checksum(ADDRESS_HRP, data)
+    return ADDRESS_HRP + "1" + "".join(_CHARSET[d] for d in combined)
+
+
+def from_omne_address(address: str) -> bytes:
+    """Decode an ``om1z…`` address to its raw 32-byte payload."""
+    lowered = address.lower()
+    pos = lowered.rfind("1")
+    if pos < 1:
+        raise ValueError(f"Invalid address (no separator): {address}")
+    hrp = lowered[:pos]
+    if hrp != ADDRESS_HRP:
+        raise ValueError(f"Invalid address HRP: expected '{ADDRESS_HRP}', got '{hrp}'")
+    try:
+        data = [_CHARSET_REV[c] for c in lowered[pos + 1:]]
+    except KeyError as exc:
+        raise ValueError(f"Invalid bech32 character in address: {address}") from exc
+    if not _verify_checksum(hrp, data):
+        raise ValueError(f"Invalid bech32m checksum: {address}")
+    payload_words = data[:-6]
+    if not payload_words or payload_words[0] != ADDRESS_WITNESS_VERSION:
+        raise ValueError("Invalid witness version")
+    payload = bytes(_convert_bits(payload_words[1:], 5, 8, False))
+    if len(payload) != ADDRESS_PAYLOAD_BYTES:
+        raise ValueError(f"Address payload must be {ADDRESS_PAYLOAD_BYTES} bytes, got {len(payload)}")
+    return payload
+
+
+def parse_address(address: str) -> bytes:
+    """Alias for :func:`from_omne_address` — returns the 32-byte payload."""
+    return from_omne_address(address)
+
+
+def derive_address_from_public_key(public_key: bytes) -> str:
+    """Canonical address derivation, shared with the Rust-side PqcAccountAddress:
+    ``to_omne_address(SHA-256("OMNE_PQC_ADDRESS_V1" || pubkey))``.
+    """
+    digest = hashlib.sha256(ADDRESS_DOMAIN_TAG + public_key).digest()
+    return to_omne_address(digest)

omne_sdk-0.1.0/src/omne_sdk/errors.py

@@ -0,0 +1,23 @@
+"""Error types for the Omne Python SDK."""
+
+from __future__ import annotations
+
+
+class OmneError(Exception):
+    """Base class for all Omne SDK errors."""
+
+
+class WalletError(OmneError):
+    """Wallet / key-derivation / signing error."""
+
+
+class ValidationError(OmneError):
+    """Invalid argument or input."""
+
+
+class RpcError(OmneError):
+    """JSON-RPC transport or node-returned error."""
+
+    def __init__(self, message: str, code: int | None = None):
+        super().__init__(message)
+        self.code = code

omne_sdk-0.1.0/src/omne_sdk/rpc.py

@@ -0,0 +1,166 @@
+"""Minimal JSON-RPC client for an Omne node (stdlib urllib — no extra deps).
+
+Mirrors the request/wire shapes the TS SDK (sdk/typescript/src/client.ts) and
+the Cinchor SDK use:
+
+  * omne_sendTransaction([wire])  — wire carries om1z addresses + a nested
+    { signature: { signature, publicKey } }; the node rebuilds the canonical
+    hash preimage and verifies the ML-DSA-44 signature.
+  * omne_call([{ to, data, from? }]) — read-only; reference-typed returns come
+    back as a 0x-hex `returnValue` (decode addresses with address.from_omne_*).
+  * omne_blockNumber, omne_getNonce, omne_getTransactionReceipt.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.request
+
+from .abi import AbiArgument, encode_contract_call
+from .errors import RpcError
+from .transaction import DEFAULT_GAS_LIMIT, DEFAULT_GAS_PRICE, build_transaction
+from .wallet import WalletAccount
+
+
+class OmneClient:
+    def __init__(self, rpc_url: str, chain_id: int, *, timeout: float = 10.0):
+        self.rpc_url = rpc_url
+        self.chain_id = chain_id
+        self.timeout = timeout
+        self._id = 0
+        # Per-signer client-side nonce cache. The node reports real nonces but
+        # only advances them on block commit, so rapid back-to-back sends within
+        # a process must be numbered locally to stay unique (identical payload +
+        # nonce => identical tx hash => dropped by gossip dedup). Seeded once per
+        # address from the node, then incremented locally; a fresh process
+        # re-seeds from the committed nonce, so uniqueness holds across restarts.
+        self._nonces: dict[str, int] = {}
+
+    # ── transport ───────────────────────────────────────────────────
+    def request(self, method: str, params: list | None = None):
+        self._id += 1
+        payload = json.dumps({"jsonrpc": "2.0", "method": method, "params": params or [], "id": self._id})
+        req = urllib.request.Request(
+            self.rpc_url,
+            data=payload.encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            body = json.loads(resp.read().decode("utf-8"))
+        if body.get("error"):
+            err = body["error"]
+            raise RpcError(str(err.get("message", err)), code=err.get("code"))
+        return body.get("result")
+
+    # ── reads ────────────────────────────────────────────────────────
+    def block_number(self) -> int:
+        return int(self.request("omne_blockNumber", []))
+
+    def get_nonce(self, address: str) -> int:
+        # Devnet note: the node does not yet enforce per-account nonces;
+        # omne_getNonce reports 0 even for a busy signer (any nonce accepted).
+        try:
+            return int(self.request("omne_getNonce", [address]) or 0)
+        except RpcError:
+            acct = self.request("omne_getAccount", [address]) or {}
+            return int(acct.get("nonce", 0))
+
+    def next_nonce(self, address: str) -> int:
+        """Allocate the next unique nonce for an address: seeded from the node's
+        committed nonce on first use, then incremented locally per call so
+        rapid sends never collide on the tx hash."""
+        if address not in self._nonces:
+            self._nonces[address] = self.get_nonce(address)
+        n = self._nonces[address]
+        self._nonces[address] = n + 1
+        return n
+
+    def call(self, to: str, data: str, sender: str | None = None) -> dict:
+        call_obj = {"to": to, "data": data}
+        if sender:
+            call_obj["from"] = sender
+        return self.request("omne_call", [call_obj])
+
+    def query_contract(self, contract: str, method: str, args: list[AbiArgument] | None = None,
+                       sender: str | None = None) -> dict:
+        """Read-only contract call. `method` is the ABI selector — for pysub
+        contracts the contract-qualified form `"<contract>::<method>"` (e.g.
+        `cinchor_permissions::get_status`). Reference (address/bytes) returns
+        come back as a `0x`-hex `returnValue`.
+        """
+        return self.call(contract, encode_contract_call(method, args or []), sender)
+
+    def get_transaction_receipt(self, tx_hash: str):
+        return self.request("omne_getTransactionReceipt", [tx_hash])
+
+    # ── writes ───────────────────────────────────────────────────────
+    @staticmethod
+    def _to_wire(signed: dict) -> dict:
+        wire = {
+            "from": signed["from"],
+            "to": signed["to"],
+            "value": signed["value"],
+            "gasLimit": signed["gasLimit"],
+            "gasPrice": signed["gasPrice"],
+            "nonce": signed["nonce"],
+            "chainId": signed["chainId"],
+            "data": signed.get("data") or "",
+            "signature": {"signature": signed["signature"], "publicKey": signed["publicKey"]},
+        }
+        if signed.get("priority"):
+            wire["priority"] = signed["priority"]
+        if signed.get("layer"):
+            wire["layer"] = signed["layer"]
+        return wire
+
+    def send_signed(self, signed: dict) -> str | None:
+        result = self.request("omne_sendTransaction", [self._to_wire(signed)])
+        if isinstance(result, str):
+            return result
+        if isinstance(result, dict):
+            return result.get("transactionHash")
+        return None
+
+    def send_contract_call(
+        self,
+        account: WalletAccount,
+        contract: str,
+        method: str,
+        args: list[AbiArgument] | None = None,
+        *,
+        value: int | str = 0,
+        gas_limit: int = DEFAULT_GAS_LIMIT,
+        gas_price: str = DEFAULT_GAS_PRICE,
+        nonce: int | None = None,
+    ) -> str | None:
+        """Build → sign → submit a state-modifying contract call."""
+        resolved_nonce = self.next_nonce(account.address) if nonce is None else nonce
+        tx = build_transaction(
+            sender=account.address,
+            to=contract,
+            data=encode_contract_call(method, args or []),
+            value=value,
+            gas_limit=gas_limit,
+            gas_price=gas_price,
+            nonce=resolved_nonce,
+            chain_id=self.chain_id,
+        )
+        signed = account.sign_transaction(tx, chain_id=self.chain_id)
+        return self.send_signed(signed)
+
+    def wait_for_receipt(self, tx_hash: str, timeout: float = 60.0, interval: float = 1.0):
+        """Poll for a receipt, tolerating 'not found' while the tx is in mempool."""
+        if not tx_hash:
+            return None
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            try:
+                receipt = self.get_transaction_receipt(tx_hash)
+                if receipt:
+                    return receipt
+            except RpcError:
+                pass  # receipt not yet available — keep polling
+            time.sleep(interval)
+        return None

omne_sdk-0.1.0/src/omne_sdk/transaction.py

@@ -0,0 +1,80 @@
+"""Transaction building + canonical hashing.
+
+The signing preimage matches the Rust-side hash_transaction() in
+omne-blockchain/src/rpc/wallet.rs and the TS wallet: fields are concatenated in
+a fixed order with little-endian numeric encoding, then SHA-256'd. The node
+reconstructs this exact preimage from the wire payload to verify the signature,
+so every signed field must round-trip byte-for-byte.
+
+    SHA-256( from(32) ‖ to(32) ‖ value(LE128) ‖ gasLimit(LE64) ‖ gasPrice(LE64)
+             ‖ nonce(LE64) ‖ chainId(LE64) ‖ data )
+
+Addresses are decoded from their om1z form to 32 raw bytes for the preimage.
+`data` is the hex-encoded ABI calldata (see abi.encode_contract_call).
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+from .address import from_omne_address, from_hex
+
+DEFAULT_GAS_LIMIT = 200_000
+DEFAULT_GAS_PRICE = "5000"
+
+
+def _le(value: int, num_bytes: int) -> bytes:
+    return int(value).to_bytes(num_bytes, "little")
+
+
+def hash_transaction(transaction: dict) -> bytes:
+    """Canonical 32-byte transaction hash used as the ML-DSA-44 signing message."""
+    if transaction.get("chainId") is None:
+        raise ValueError("chainId must be set on the transaction before hashing")
+
+    from_bytes = from_omne_address(transaction["from"])
+    to = transaction.get("to")
+    to_bytes = from_omne_address(to) if to else b""
+
+    data = transaction.get("data") or ""
+    data_bytes = from_hex(data) if data else b""
+
+    preimage = b"".join(
+        [
+            from_bytes,
+            to_bytes,
+            _le(int(transaction["value"]), 16),
+            _le(int(transaction["gasLimit"]), 8),
+            _le(int(transaction["gasPrice"]), 8),
+            _le(int(transaction["nonce"]), 8),
+            _le(int(transaction["chainId"]), 8),
+            data_bytes,
+        ]
+    )
+    return hashlib.sha256(preimage).digest()
+
+
+def build_transaction(
+    *,
+    sender: str,
+    to: str,
+    data: str = "",
+    value: int | str = 0,
+    gas_limit: int = DEFAULT_GAS_LIMIT,
+    gas_price: str = DEFAULT_GAS_PRICE,
+    nonce: int = 0,
+    chain_id: int | None = None,
+) -> dict:
+    """Build an unsigned transaction dict ready for WalletAccount.sign_transaction."""
+    tx: dict = {
+        "from": sender,
+        "to": to,
+        "value": str(value),
+        "gasLimit": gas_limit,
+        "gasPrice": gas_price,
+        "nonce": nonce,
+        "data": data,
+    }
+    if chain_id is not None:
+        tx["chainId"] = chain_id
+    return tx

omne_sdk-0.1.0/src/omne_sdk/wallet.py

@@ -0,0 +1,144 @@
+"""Mnemonic-based HD wallet + ML-DSA-44 (FIPS 204) signing for Omne.
+
+Port of sdk/typescript/src/wallet.ts. Omne is post-quantum from the ground up:
+all signing is ML-DSA-44 (FIPS 204). A 32-byte seed is the portable secret; the
+keypair (1312-byte public key, 2560-byte secret key) is deterministically
+expanded from it via ML-DSA-44 KeyGen_internal.
+
+Key derivation is an HMAC-SHA512 hierarchical KDF (hardened-only) over the
+BIP39 seed, identical to the TS wallet — so the same mnemonic yields the same
+addresses across both SDKs (parity-verified in tests/test_parity.py).
+
+ML-DSA-44 keygen/sign come from `dilithium-py` (pinned), whose public
+`key_derive(xi)` is byte-identical to the TS SDK's `@noble/post-quantum`
+`ml_dsa44.keygen(seed)` (verified). Signatures cross-verify in both directions
+and are accepted by the node's verify path.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import unicodedata
+
+from dilithium_py.ml_dsa import ML_DSA_44
+
+from .address import derive_address_from_public_key, from_omne_address
+from .errors import WalletError
+from .transaction import hash_transaction
+
+_BASE_PATH = "m/44'/60'/0'/0"
+_HD_MASTER_KEY = b"omne ml-dsa44 seed"
+
+
+# ── BIP39 mnemonic -> 64-byte seed ──────────────────────────────────
+def mnemonic_to_seed(mnemonic: str, passphrase: str = "") -> bytes:
+    """BIP39 seed: PBKDF2-HMAC-SHA512(NFKD(mnemonic), "mnemonic"+passphrase, 2048)."""
+    m = unicodedata.normalize("NFKD", mnemonic).encode("utf-8")
+    salt = unicodedata.normalize("NFKD", "mnemonic" + passphrase).encode("utf-8")
+    return hashlib.pbkdf2_hmac("sha512", m, salt, 2048, dklen=64)
+
+
+# ── Omne HD KDF (hardened-only HMAC-SHA512) ─────────────────────────
+def _hd_master(seed: bytes) -> tuple[bytes, bytes]:
+    i = hmac.new(_HD_MASTER_KEY, seed, hashlib.sha512).digest()
+    return i[:32], i[32:]
+
+
+def _hd_child(parent_seed: bytes, parent_chain: bytes, index: int) -> tuple[bytes, bytes]:
+    hardened = (index | 0x80000000) & 0xFFFFFFFF
+    data = b"\x00" + parent_seed + hardened.to_bytes(4, "big")
+    i = hmac.new(parent_chain, data, hashlib.sha512).digest()
+    return i[:32], i[32:]
+
+
+def _hd_derive_path(seed: bytes, path: str) -> bytes:
+    segments = [s for s in path.replace("m/", "").split("/") if s]
+    cur_seed, cur_chain = _hd_master(seed)
+    for seg in segments:
+        try:
+            idx = int(seg.replace("'", ""))
+        except ValueError as exc:
+            raise WalletError(f"Invalid derivation path segment: {seg}") from exc
+        cur_seed, cur_chain = _hd_child(cur_seed, cur_chain, idx)
+    return cur_seed
+
+
+class WalletAccount:
+    """A single account: a 32-byte seed expanded to an ML-DSA-44 keypair."""
+
+    def __init__(self, private_key: str, path: str | None = None):
+        if len(private_key) != 64 or any(c not in "0123456789abcdef" for c in private_key.lower()):
+            raise WalletError("Invalid private key: expected 64 hex chars (32-byte ML-DSA-44 seed)")
+        self.private_key = private_key.lower()
+        self.path = path
+        seed = bytes.fromhex(self.private_key)
+        # key_derive(xi) is dilithium-py's PUBLIC, documented (FIPS 204 §6.1)
+        # deterministic keygen from a 32-byte seed — byte-identical to the TS
+        # SDK's @noble ml_dsa44.keygen(seed). Public API (not the _keygen_internal
+        # private method) so it is part of the lib's stability contract.
+        public_key, secret_key = ML_DSA_44.key_derive(seed)
+        self._secret_key = secret_key  # 2560 bytes, never exported
+        self.public_key = public_key.hex()
+        self.address = derive_address_from_public_key(public_key)
+
+    @classmethod
+    def from_private_key(cls, private_key: str) -> "WalletAccount":
+        return cls(private_key)
+
+    def sign_hash(self, digest: bytes) -> bytes:
+        """ML-DSA-44 signature (2420 bytes, empty context — matches the node)."""
+        return ML_DSA_44.sign(self._secret_key, digest, ctx=b"")
+
+    def sign_message(self, message: str) -> str:
+        """Sign SHA-256(message); appends the 1312-byte pubkey (ML-DSA has no recovery)."""
+        digest = hashlib.sha256(message.encode("utf-8")).digest()
+        signature = self.sign_hash(digest)
+        return (signature + bytes.fromhex(self.public_key)).hex()
+
+    def sign_transaction(self, transaction: dict, chain_id: int | None = None) -> dict:
+        """Sign a transaction. Returns the tx augmented with chainId, signature, publicKey.
+
+        The hash preimage matches the Rust-side hash_transaction() and the TS
+        wallet: canonical field concat with little-endian numbers.
+        """
+        resolved = chain_id if chain_id is not None else transaction.get("chainId")
+        if resolved is None:
+            raise WalletError("chainId required for signing (e.g. 3 for Ignis)")
+        normalized = {**transaction, "chainId": resolved}
+        tx_hash = hash_transaction(normalized)
+        signature = self.sign_hash(tx_hash)
+        return {
+            **normalized,
+            "signature": signature.hex(),
+            "publicKey": self.public_key,
+        }
+
+
+class Wallet:
+    """HD wallet with BIP39 mnemonic support (hardened-only HMAC-SHA512 KDF)."""
+
+    def __init__(self, mnemonic: str, passphrase: str = ""):
+        # NOTE: mnemonic checksum validation against the BIP39 wordlist is a
+        # follow-up; seed derivation (the parity-critical path) is exact.
+        self.mnemonic = mnemonic
+        self._seed = mnemonic_to_seed(mnemonic, passphrase)
+
+    @classmethod
+    def from_mnemonic(cls, mnemonic: str, passphrase: str = "") -> "Wallet":
+        return cls(mnemonic, passphrase)
+
+    @classmethod
+    def from_private_key(cls, private_key: str) -> WalletAccount:
+        return WalletAccount.from_private_key(private_key)
+
+    def get_account(self, index: int = 0) -> WalletAccount:
+        if index < 0:
+            raise WalletError(f"Account index must be non-negative: {index}")
+        path = f"{_BASE_PATH}/{index}"
+        seed = _hd_derive_path(self._seed, path)
+        return WalletAccount(seed.hex(), path)
+
+    @property
+    def address(self) -> str:
+        return self.get_account(0).address

omne_sdk-0.1.0/tests/test_parity.py

@@ -0,0 +1,65 @@
+"""Cross-SDK parity tests.
+
+These pin the Python SDK to byte-for-byte agreement with the TypeScript SDK
+(@omne/sdk + @noble/post-quantum). Vectors were captured from the TS SDK:
+  * keygen vectors: ml_dsa44.keygen(seed) public-key SHA-256 for fixed seeds.
+  * chain vector: Wallet.fromMnemonic(<canonical BIP39 test mnemonic>)
+    .getAccount(0) -> HD seed, pubkey SHA-256, om1z address.
+
+No node required — pure crypto/address parity. The live-mesh proof (a Python
+account minting/enforcing against Cinchor) is the integration test run on a mesh.
+"""
+
+import hashlib
+
+from dilithium_py.ml_dsa import ML_DSA_44
+
+from omne_sdk import Wallet, AbiEncode, encode_contract_call
+from omne_sdk.address import from_omne_address, to_omne_address
+
+# Canonical BIP39 test mnemonic (public, not a real key) — vector from the TS SDK.
+TEST_MNEMONIC = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
+EXPECTED_HD_SEED = "d6f8deee4da4c94e81c8e0e53a61f584bf15a540b48516273fc1bfe27006612d"
+EXPECTED_PUBKEY_SHA256 = "a875fccc8fd28539d6249741acef4e3c6333822707e39ed019c49d0fc1fcc5fc"
+EXPECTED_ADDRESS = "om1z6n2ydj89l7e6wq3eravk35er4jx66r63q48wfgh4ql6x0p566rvsj22jgp"
+
+
+def _pk_sha256(seed: bytes) -> str:
+    pk, _ = ML_DSA_44.key_derive(seed)  # public seed-keygen the SDK uses
+    return hashlib.sha256(pk).hexdigest()
+
+
+def test_keygen_zero_seed_matches_noble():
+    assert _pk_sha256(bytes(32)) == "eb4e7302842153b0fa19e8620739ad258af4929c26dd89079a7ec7d4282208e1"
+
+
+def test_keygen_iota_seed_matches_noble():
+    assert _pk_sha256(bytes(range(32))) == "9f107644c1084526af3bc8098680b05499a2325a644e388fb4f970e058d19d46"
+
+
+def test_full_chain_mnemonic_to_address():
+    account = Wallet.from_mnemonic(TEST_MNEMONIC).get_account(0)
+    assert account.private_key == EXPECTED_HD_SEED
+    assert hashlib.sha256(bytes.fromhex(account.public_key)).hexdigest() == EXPECTED_PUBKEY_SHA256
+    assert account.address == EXPECTED_ADDRESS
+
+
+def test_address_roundtrip():
+    payload = from_omne_address(EXPECTED_ADDRESS)
+    assert len(payload) == 32
+    assert to_omne_address(payload) == EXPECTED_ADDRESS
+
+
+def test_sign_then_verify():
+    account = Wallet.from_mnemonic(TEST_MNEMONIC).get_account(0)
+    digest = hashlib.sha256(b"omne-parity-test").digest()
+    sig = account.sign_hash(digest)
+    assert len(sig) == 2420  # ML-DSA-44 signature length
+    pk = bytes.fromhex(account.public_key)
+    assert ML_DSA_44.verify(pk, digest, sig, ctx=b"") is True
+
+
+def test_abi_encode_contract_call_shape():
+    data = encode_contract_call("get_principal", [AbiEncode.address(EXPECTED_ADDRESS)])
+    assert data.startswith("4f4d4e45")  # "OMNE" magic
+    assert bytes.fromhex(data)[4] == 0x01  # version