ault-sdk 0.0.1a1__py3-none-any.whl

ault_sdk/__init__.py

@@ -0,0 +1,205 @@
+"""Ault SDK for Python.
+
+Public API mirrors ``ault-sdk-ts``'s ``src/index.ts`` with Python
+naming conventions (snake_case methods, dataclasses where TS uses
+object-literal types). See ``DECISIONS.md`` for the deviations.
+"""
+
+from __future__ import annotations
+
+from ault_sdk._version import SDK_VERSION
+
+# Core
+from ault_sdk.agent import (
+    AGENT_DEFAULTS,
+    AgentClient,
+    AgentClientOptions,
+    AgentKeyMaterial,
+    AgentSignAndBroadcastParams,
+    compute_agent_key_material,
+    create_agent_client,
+    sign_and_broadcast_agent_tx,
+)
+from ault_sdk.client import AultClient, create_ault_client
+from ault_sdk.core.base64 import base64_to_bytes, bytes_to_base64
+from ault_sdk.core.errors import (
+    ApiError,
+    AultError,
+    NetworkError,
+    TimeoutError,
+    WebSocketError,
+)
+from ault_sdk.core.http import (
+    FetchOptions,
+    HttpContext,
+    fetch_json,
+    fetch_with_retry,
+    post_json,
+)
+from ault_sdk.core.network import (
+    DEFAULT_CHAIN_ID,
+    GAS_CONSTANTS,
+    NETWORKS,
+    TIMING_CONSTANTS,
+    NetworkConfig,
+    compute_fee_free_gas,
+    compute_fee_free_gas_compound,
+    get_network_config,
+)
+from ault_sdk.core.pagination import PaginationResult, paginate_all
+from ault_sdk.eip712.builder import (
+    Eip712Msg,
+    Eip712TxContext,
+    build_eip712_amino_msg,
+    build_eip712_amino_sign_doc,
+    build_eip712_typed_data,
+)
+from ault_sdk.eip712.msg_encoders_generated import MSG_ENCODERS
+from ault_sdk.eip712.msg_generated import msg
+from ault_sdk.eip712.registry import EIP712_MSG_TYPES, Eip712MsgTypeConfig, FieldSemantics
+from ault_sdk.eip712.sign_and_broadcast import (
+    AccountCache,
+    BroadcastResult,
+    SignAndBroadcastParams,
+    create_account_cache,
+    query_account,
+    sign_and_broadcast_eip712,
+)
+from ault_sdk.eip712.signers import (
+    Eip1193Signer,
+    PrivateKeySigner,
+    SignerInput,
+    TypedDataSigner,
+    normalize_signer,
+    resolve_signer_address,
+)
+from ault_sdk.eip712.types import Eip712TypedData
+from ault_sdk.evm import (
+    BANK_DECIMALS,
+    BridgeParams,
+    CreateEvmClientOptions,
+    Erc20Metadata,
+    Erc20Reader,
+    Erc20TransferParams,
+    Erc20Writer,
+    EvmClient,
+    TokenBridge,
+    TokenInfo,
+    TokenRegistryEvm,
+    create_erc20_reader,
+    create_erc20_writer,
+    create_evm_client,
+    create_token_bridge,
+    create_token_registry_evm,
+    format_bank_amount,
+    format_token_units,
+    parse_bank_amount,
+    parse_token_units,
+)
+from ault_sdk.high_level import Client, ClientOptions, create_client
+from ault_sdk.utils.address import (
+    ault_to_evm,
+    evm_to_ault,
+    is_valid_ault_address,
+    is_valid_evm_address,
+    resolve_address_to_bech32,
+    resolve_address_to_evm,
+)
+from ault_sdk.utils.chain_id import parse_evm_chain_id_from_cosmos_chain_id
+from ault_sdk.utils.cosmos_dec import cosmos_dec_to_decimal_string, cosmos_dec_to_proto_int
+from ault_sdk.ws import DexWsClient, DexWsOptions, SubscriptionHandlers, create_dex_ws
+
+__all__ = [
+    "AGENT_DEFAULTS",
+    "BANK_DECIMALS",
+    "DEFAULT_CHAIN_ID",
+    "EIP712_MSG_TYPES",
+    "GAS_CONSTANTS",
+    "MSG_ENCODERS",
+    "NETWORKS",
+    "SDK_VERSION",
+    "TIMING_CONSTANTS",
+    "AccountCache",
+    "AgentClient",
+    "AgentClientOptions",
+    "AgentKeyMaterial",
+    "AgentSignAndBroadcastParams",
+    "ApiError",
+    "AultClient",
+    "AultError",
+    "BridgeParams",
+    "BroadcastResult",
+    "Client",
+    "ClientOptions",
+    "CreateEvmClientOptions",
+    "DexWsClient",
+    "DexWsOptions",
+    "Eip712Msg",
+    "Eip712MsgTypeConfig",
+    "Eip712TxContext",
+    "Eip712TypedData",
+    "Eip1193Signer",
+    "Erc20Metadata",
+    "Erc20Reader",
+    "Erc20TransferParams",
+    "Erc20Writer",
+    "EvmClient",
+    "FetchOptions",
+    "FieldSemantics",
+    "HttpContext",
+    "NetworkConfig",
+    "NetworkError",
+    "PaginationResult",
+    "PrivateKeySigner",
+    "SignAndBroadcastParams",
+    "SignerInput",
+    "SubscriptionHandlers",
+    "TimeoutError",
+    "TokenBridge",
+    "TokenInfo",
+    "TokenRegistryEvm",
+    "TypedDataSigner",
+    "WebSocketError",
+    "ault_to_evm",
+    "base64_to_bytes",
+    "build_eip712_amino_msg",
+    "build_eip712_amino_sign_doc",
+    "build_eip712_typed_data",
+    "bytes_to_base64",
+    "compute_agent_key_material",
+    "compute_fee_free_gas",
+    "compute_fee_free_gas_compound",
+    "cosmos_dec_to_decimal_string",
+    "cosmos_dec_to_proto_int",
+    "create_account_cache",
+    "create_agent_client",
+    "create_ault_client",
+    "create_client",
+    "create_dex_ws",
+    "create_erc20_reader",
+    "create_erc20_writer",
+    "create_evm_client",
+    "create_token_bridge",
+    "create_token_registry_evm",
+    "evm_to_ault",
+    "fetch_json",
+    "fetch_with_retry",
+    "format_bank_amount",
+    "format_token_units",
+    "get_network_config",
+    "is_valid_ault_address",
+    "is_valid_evm_address",
+    "msg",
+    "normalize_signer",
+    "paginate_all",
+    "parse_bank_amount",
+    "parse_evm_chain_id_from_cosmos_chain_id",
+    "parse_token_units",
+    "post_json",
+    "query_account",
+    "resolve_address_to_bech32",
+    "resolve_address_to_evm",
+    "resolve_signer_address",
+    "sign_and_broadcast_agent_tx",
+    "sign_and_broadcast_eip712",
+]

ault_sdk/_version.py

@@ -0,0 +1,9 @@
+"""Single source of truth for the SDK version string.
+
+Kept separate from ``__init__.py`` so codegen scripts and build tooling can
+read the version without importing the full package.
+"""
+
+from __future__ import annotations
+
+SDK_VERSION: str = "0.0.1a0"

ault_sdk/agent/__init__.py

@@ -0,0 +1,31 @@
+"""Agent client + agent-specific tx signing. Mirrors ``src/agent``."""
+
+from __future__ import annotations
+
+from ault_sdk.agent.create_agent_client import AgentClient, AgentClientOptions, create_agent_client
+from ault_sdk.agent.sign_and_broadcast import (
+    AGENT_DEFAULTS,
+    AgentKeyMaterial,
+    AgentSignAndBroadcastParams,
+    compute_agent_key_material,
+    sign_and_broadcast_agent_tx,
+)
+from ault_sdk.agent.tx_executor import (
+    AgentTxExecutor,
+    AgentTxExecutorOptions,
+    create_agent_tx_executor,
+)
+
+__all__ = [
+    "AGENT_DEFAULTS",
+    "AgentClient",
+    "AgentClientOptions",
+    "AgentKeyMaterial",
+    "AgentSignAndBroadcastParams",
+    "AgentTxExecutor",
+    "AgentTxExecutorOptions",
+    "compute_agent_key_material",
+    "create_agent_client",
+    "create_agent_tx_executor",
+    "sign_and_broadcast_agent_tx",
+]

ault_sdk/agent/create_agent_client.py

@@ -0,0 +1,172 @@
+"""Agent client factory."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+from eth_keys import keys
+from eth_utils import keccak, to_checksum_address
+
+from ault_sdk.agent.tx_executor import (
+    AgentTxExecutor,
+    AgentTxExecutorOptions,
+    AgentTxOptions,
+    create_agent_tx_executor,
+)
+from ault_sdk.client import AultClient, create_ault_client
+from ault_sdk.core.address import normalize_address
+from ault_sdk.core.clob_msgs import (
+    build_cancel_orders_msg,
+    build_limit_order_msg,
+    build_market_order_msg,
+    build_scale_order_msg,
+)
+from ault_sdk.core.http import FetchOptions
+from ault_sdk.core.network import (
+    GAS_CONSTANTS,
+    NetworkConfig,
+    compute_fee_free_gas,
+    compute_fee_free_gas_compound,
+)
+from ault_sdk.high_level.tx_executor import TxResult
+from ault_sdk.utils.address import evm_to_ault
+
+
+def _derive_agent_address(agent_private_key: str) -> str:
+    """Derive the bech32 address from a secp256k1 private key."""
+
+    normalized = (
+        agent_private_key[2:] if agent_private_key.startswith(("0x", "0X")) else agent_private_key
+    )
+    private_key = keys.PrivateKey(bytes.fromhex(normalized))
+    uncompressed = private_key.public_key.to_bytes()  # 64 bytes (x || y)
+    evm_address = "0x" + keccak(uncompressed)[-20:].hex()
+    return evm_to_ault(to_checksum_address(evm_address))
+
+
+@dataclass(slots=True)
+class AgentClientOptions:
+    network: NetworkConfig
+    master_address: str
+    agent_private_key: str
+    client: httpx.AsyncClient | None = None
+    fetch_options: FetchOptions | None = None
+    default_gas_limit: str | None = None
+    default_memo: str = ""
+    default_confirmation_timeout_ms: int | None = None
+    default_timeout_seconds: int | None = None
+
+
+class AgentClient:
+    __slots__ = (
+        "_exec",
+        "_low_level",
+        "agent",
+        "agent_address",
+        "clob",
+        "market",
+        "master_address",
+        "network",
+    )
+
+    def __init__(
+        self,
+        *,
+        low_level: AultClient,
+        master_address: str,
+        agent_address: str,
+        exec_: AgentTxExecutor,
+    ) -> None:
+        self.network = low_level.network
+        self.master_address = master_address
+        self.agent_address = agent_address
+        self._low_level = low_level
+        self._exec = exec_
+        self.agent = low_level.rest.agent
+        self.clob = low_level.rest.clob
+        self.market = low_level.rest.market
+
+    async def place_limit_order(self, **params: Any) -> TxResult:
+        gas = params.pop("gas_limit", None) or compute_fee_free_gas(GAS_CONSTANTS.LIMIT_ORDER, 1)
+        opts = AgentTxOptions(
+            gas_limit=gas,
+            memo=params.pop("memo", None),
+            confirmation_timeout_ms=params.pop("confirmation_timeout_ms", None),
+            timeout_seconds=params.pop("timeout_seconds", None),
+        )
+        return await self._exec([build_limit_order_msg(self.master_address, params)], opts)
+
+    async def place_market_order(self, **params: Any) -> TxResult:
+        gas = params.pop("gas_limit", None) or compute_fee_free_gas(GAS_CONSTANTS.MARKET_ORDER, 1)
+        opts = AgentTxOptions(
+            gas_limit=gas,
+            memo=params.pop("memo", None),
+            confirmation_timeout_ms=params.pop("confirmation_timeout_ms", None),
+            timeout_seconds=params.pop("timeout_seconds", None),
+        )
+        return await self._exec([build_market_order_msg(self.master_address, params)], opts)
+
+    async def cancel_orders(self, *, order_ids: list[bytes], **opts: Any) -> TxResult:
+        gas = opts.pop("gas_limit", None) or compute_fee_free_gas_compound(
+            GAS_CONSTANTS.CANCEL_ORDER_BASE,
+            GAS_CONSTANTS.CANCEL_ORDER_PER_ID,
+            len(order_ids),
+        )
+        agent_opts = AgentTxOptions(
+            gas_limit=gas,
+            memo=opts.pop("memo", None),
+            confirmation_timeout_ms=opts.pop("confirmation_timeout_ms", None),
+            timeout_seconds=opts.pop("timeout_seconds", None),
+        )
+        return await self._exec(
+            [build_cancel_orders_msg(self.master_address, order_ids)], agent_opts
+        )
+
+    async def place_scale_order(self, **params: Any) -> TxResult:
+        weights = params.get("weights", [])
+        gas = params.pop("gas_limit", None) or compute_fee_free_gas_compound(
+            GAS_CONSTANTS.SCALE_ORDER_BASE,
+            GAS_CONSTANTS.SCALE_ORDER_PER_SUB,
+            len(weights),
+        )
+        opts = AgentTxOptions(
+            gas_limit=gas,
+            memo=params.pop("memo", None),
+            confirmation_timeout_ms=params.pop("confirmation_timeout_ms", None),
+            timeout_seconds=params.pop("timeout_seconds", None),
+        )
+        return await self._exec([build_scale_order_msg(self.master_address, params)], opts)
+
+
+async def create_agent_client(options: AgentClientOptions) -> AgentClient:
+    master_address = normalize_address(options.master_address)
+    agent_address = _derive_agent_address(options.agent_private_key)
+    low_level = create_ault_client(
+        network=options.network,
+        client=options.client,
+        options=options.fetch_options,
+    )
+    exec_ = create_agent_tx_executor(
+        AgentTxExecutorOptions(
+            network=options.network,
+            agent_private_key=options.agent_private_key,
+            master_address=master_address,
+            client=options.client,
+            fetch_options=options.fetch_options,
+            default_gas_limit=options.default_gas_limit,
+            default_memo=options.default_memo,
+            default_confirmation_timeout_ms=options.default_confirmation_timeout_ms,
+            default_timeout_seconds=options.default_timeout_seconds,
+        )
+    )
+    return AgentClient(
+        low_level=low_level,
+        master_address=master_address,
+        agent_address=agent_address,
+        exec_=exec_,
+    )
+
+
+__all__ = ["AgentClient", "AgentClientOptions", "create_agent_client"]

ault_sdk/agent/sign_and_broadcast.py

@@ -0,0 +1,237 @@
+"""Agent transaction signing (SIGN_MODE_DIRECT + agent extension option).
+
+Mirrors ``src/agent/sign-and-broadcast.ts``. Agent txs carry a
+``tokenregistry.v1.ExtensionOptionsAgentTx`` and are signed with raw
+secp256k1 over the keccak256 of the SignDoc.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+from eth_keys import keys
+from eth_utils import keccak
+
+from ault_sdk.core.base64 import bytes_to_base64
+from ault_sdk.core.http import FetchOptions, post_json
+from ault_sdk.core.network import NetworkConfig
+from ault_sdk.eip712.builder import Eip712Msg
+from ault_sdk.eip712.msg_encoders_generated import MSG_ENCODERS
+from ault_sdk.eip712.sign_and_broadcast import (
+    AccountCache,
+    BroadcastResult,
+    poll_tx_inclusion,
+    query_account,
+)
+from ault_sdk.proto.tx_encode import (
+    SIGN_MODE_DIRECT,
+    AgentTxBody,
+    AnyMsg,
+    AuthInfo,
+    SignDoc,
+    SignerInfo,
+    TimeoutTimestamp,
+    TxFee,
+    TxRaw,
+    encode_auth_info,
+    encode_eth_secp256k1_pubkey,
+    encode_sign_doc,
+    encode_tx_body_agent,
+    encode_tx_raw,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class _AgentDefaults:
+    GAS_LIMIT: str = "147600"
+    TIMEOUT_SECONDS: int = 300
+    EXTENSION_TYPE_URL: str = "/ault.agent.v1.ExtensionOptionsAgentTx"
+    PUBKEY_TYPE_URL: str = "/cosmos.evm.crypto.v1.ethsecp256k1.PubKey"
+
+
+AGENT_DEFAULTS = _AgentDefaults()
+
+
+@dataclass(slots=True)
+class AgentKeyMaterial:
+    priv_key_bytes: bytes
+    compressed_pubkey: bytes
+
+
+def compute_agent_key_material(agent_private_key: str) -> AgentKeyMaterial:
+    normalized = (
+        agent_private_key[2:] if agent_private_key.startswith(("0x", "0X")) else agent_private_key
+    )
+    priv = bytes.fromhex(normalized)
+    private_key = keys.PrivateKey(priv)
+    return AgentKeyMaterial(
+        priv_key_bytes=priv,
+        compressed_pubkey=private_key.public_key.to_compressed_bytes(),
+    )
+
+
+@dataclass(slots=True)
+class AgentSignAndBroadcastParams:
+    network: NetworkConfig
+    key_material: AgentKeyMaterial
+    master_address: str
+    msgs: Sequence[Eip712Msg]
+    memo: str = ""
+    gas_limit: str | None = None
+    confirmation_timeout_ms: int | None = None
+    timeout_seconds: int | None = None
+    timeout_timestamp: TimeoutTimestamp | None = None
+    client: httpx.AsyncClient | None = None
+    fetch_options: FetchOptions | None = None
+    cache: AccountCache | None = None
+
+
+def _compute_timeout_timestamp(timeout_seconds: int) -> TimeoutTimestamp:
+    now_ms = int(time.time() * 1000)
+    deadline_ms = now_ms + timeout_seconds * 1000
+    return TimeoutTimestamp(
+        seconds=deadline_ms // 1000,
+        nanos=(deadline_ms % 1000) * 1_000_000,
+    )
+
+
+async def sign_and_broadcast_agent_tx(
+    params: AgentSignAndBroadcastParams,
+) -> BroadcastResult:
+    key_material = params.key_material
+    cache = params.cache
+
+    # Agent txs use master's accountNumber + sequence=0; we only need
+    # accountNumber which we can cache.
+    if cache is not None and cache.account_number is not None:
+        account_number = cache.account_number
+    else:
+        info = await query_account(
+            params.network,
+            params.master_address,
+            client=params.client,
+            fetch_options=params.fetch_options,
+        )
+        account_number = info.account_number
+        if cache is not None:
+            cache.account_number = account_number
+
+    gas_limit = params.gas_limit or AGENT_DEFAULTS.GAS_LIMIT
+    timeout_seconds = (
+        params.timeout_seconds
+        if params.timeout_seconds is not None
+        else AGENT_DEFAULTS.TIMEOUT_SECONDS
+    )
+    timeout_ts = params.timeout_timestamp or _compute_timeout_timestamp(timeout_seconds)
+
+    encoded_messages: list[AnyMsg] = []
+    for m in params.msgs:
+        encoder = MSG_ENCODERS.get(m.type_url)
+        if encoder is None:
+            raise ValueError(f"No encoder found for message type: {m.type_url}")
+        encoded_messages.append(AnyMsg(type_url=m.type_url, value=encoder(m.value)))
+
+    body_bytes = encode_tx_body_agent(
+        AgentTxBody(
+            messages=encoded_messages,
+            memo=params.memo,
+            unordered=True,
+            timeout_timestamp=timeout_ts,
+            extension_options=[
+                AnyMsg(type_url=AGENT_DEFAULTS.EXTENSION_TYPE_URL, value=b""),
+            ],
+        )
+    )
+
+    pubkey_proto = encode_eth_secp256k1_pubkey(key_material.compressed_pubkey)
+    auth_info_bytes = encode_auth_info(
+        AuthInfo(
+            signer_infos=[
+                SignerInfo(
+                    public_key=AnyMsg(type_url=AGENT_DEFAULTS.PUBKEY_TYPE_URL, value=pubkey_proto),
+                    mode=SIGN_MODE_DIRECT,
+                    sequence=0,
+                )
+            ],
+            fee=TxFee(amount=[], gas_limit=int(gas_limit)),
+        )
+    )
+
+    sign_doc_bytes = encode_sign_doc(
+        SignDoc(
+            body_bytes=body_bytes,
+            auth_info_bytes=auth_info_bytes,
+            chain_id=params.network.chain_id,
+            account_number=int(account_number),
+        )
+    )
+
+    msg_hash = keccak(sign_doc_bytes)
+    private_key = keys.PrivateKey(key_material.priv_key_bytes)
+    signature = private_key.sign_msg_hash(msg_hash)
+    signature_bytes = signature.to_bytes()[:64]
+
+    tx_raw_bytes = encode_tx_raw(
+        TxRaw(
+            body_bytes=body_bytes,
+            auth_info_bytes=auth_info_bytes,
+            signatures=[signature_bytes],
+        )
+    )
+    tx_bytes_b64 = bytes_to_base64(tx_raw_bytes)
+
+    # Agent txs are unordered (line above sets `unordered=True`), so any
+    # successfully delivered duplicate broadcast becomes a duplicate
+    # on-chain action. Force `retries=0` here, matching the EIP-712
+    # broadcast path (eip712/sign_and_broadcast.py:419).
+    result = await post_json(
+        f"{params.network.rest_url}/cosmos/tx/v1beta1/txs",
+        {"tx_bytes": tx_bytes_b64, "mode": "BROADCAST_MODE_SYNC"},
+        options=FetchOptions(retries=0),
+        client=params.client,
+    )
+    tx_response: dict[str, Any] = (result or {}).get("tx_response") or {}
+    tx_hash = str(tx_response.get("txhash", ""))
+    check_code = int(tx_response.get("code", 0))
+
+    if check_code != 0:
+        return BroadcastResult(
+            tx_hash=tx_hash,
+            code=check_code,
+            raw_log=tx_response.get("raw_log"),
+            confirmed=True,
+        )
+
+    deliver = await poll_tx_inclusion(
+        params.network,
+        tx_hash,
+        client=params.client,
+        fetch_options=params.fetch_options,
+        timeout_ms=params.confirmation_timeout_ms,
+    )
+    if deliver.confirmed is None:
+        return BroadcastResult(
+            tx_hash=tx_hash,
+            code=check_code,
+            raw_log=deliver.raw_log or tx_response.get("raw_log"),
+            confirmed=None,
+        )
+    return BroadcastResult(
+        tx_hash=tx_hash,
+        code=deliver.code,
+        raw_log=deliver.raw_log,
+        confirmed=deliver.confirmed,
+    )
+
+
+__all__ = [
+    "AGENT_DEFAULTS",
+    "AgentKeyMaterial",
+    "AgentSignAndBroadcastParams",
+    "compute_agent_key_material",
+    "sign_and_broadcast_agent_tx",
+]