aeko-sdk 0.1.0__tar.gz

aeko_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: aeko-sdk
+Version: 0.1.0
+Summary: AEKO Chain Python SDK
+Author-email: AEKO Chain Maintainers <maintainers@aeko.chain>
+License: Apache-2.0
+Project-URL: Homepage, https://chain.aeko.social/
+Project-URL: Repository, https://github.com/MilliHub-dev/aeko-chain
+Project-URL: Documentation, https://github.com/MilliHub-dev/aeko-chain/tree/main/sdk/python
+Keywords: aeko,blockchain,python,sdk,rpc
+Classifier: Development Status :: 3 - Alpha
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# AEKO Python SDK
+
+`aeko-sdk` is the Python SDK for AEKO Chain scripting, automation, analytics, and operational tooling.
+
+Current scope:
+
+- JSON-RPC connection wrapper
+- account and balance queries
+- transaction submit and signature status queries
+- AEKO-721 account decoders and instruction builders
+- wallet-permissions account decoder and instruction builders
+- lightweight helpers for analytics and monitoring scripts
+
+Examples:
+
+- [`examples/basic_usage.py`](/Users/ok/Documents/projects/aeko-chain/sdk/python/examples/basic_usage.py)
+- [`examples/account_watch.py`](/Users/ok/Documents/projects/aeko-chain/sdk/python/examples/account_watch.py)
+
+## Local Verification
+
+```bash
+python3 -m compileall sdk/python/src sdk/python/examples
+```
+
+## Local Install
+
+```bash
+pip install -e sdk/python
+```

aeko_sdk-0.1.0/README.md

@@ -0,0 +1,29 @@
+# AEKO Python SDK
+
+`aeko-sdk` is the Python SDK for AEKO Chain scripting, automation, analytics, and operational tooling.
+
+Current scope:
+
+- JSON-RPC connection wrapper
+- account and balance queries
+- transaction submit and signature status queries
+- AEKO-721 account decoders and instruction builders
+- wallet-permissions account decoder and instruction builders
+- lightweight helpers for analytics and monitoring scripts
+
+Examples:
+
+- [`examples/basic_usage.py`](/Users/ok/Documents/projects/aeko-chain/sdk/python/examples/basic_usage.py)
+- [`examples/account_watch.py`](/Users/ok/Documents/projects/aeko-chain/sdk/python/examples/account_watch.py)
+
+## Local Verification
+
+```bash
+python3 -m compileall sdk/python/src sdk/python/examples
+```
+
+## Local Install
+
+```bash
+pip install -e sdk/python
+```

aeko_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aeko-sdk"
+version = "0.1.0"
+description = "AEKO Chain Python SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [
+  { name = "AEKO Chain Maintainers", email = "maintainers@aeko.chain" }
+]
+keywords = ["aeko", "blockchain", "python", "sdk", "rpc"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Homepage = "https://chain.aeko.social/"
+Repository = "https://github.com/MilliHub-dev/aeko-chain"
+Documentation = "https://github.com/MilliHub-dev/aeko-chain/tree/main/sdk/python"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

aeko_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aeko_sdk-0.1.0/src/aeko_sdk/__init__.py

@@ -0,0 +1,42 @@
+from .accounts import (
+    TOKEN_721_PROGRAM_ID,
+    WALLET_PERMISSIONS_PROGRAM_ID,
+    WalletPermissionAccount,
+    get_token_721_collection,
+    get_token_721_token,
+    get_wallet_permission_account,
+)
+from .builders import (
+    MetadataAttributeInput,
+    Token721MetadataInput,
+    build_freeze_wallet_instruction,
+    build_initialize_collection_instruction,
+    build_initialize_wallet_permissions_instruction,
+    build_mint_nft_instruction,
+    build_transfer_nft_instruction,
+    build_update_metadata_instruction,
+)
+from .client import AekoClient
+from .errors import AekoRpcError
+from .types import RpcResponse, SignatureStatusResponse
+
+__all__ = [
+    "AekoClient",
+    "AekoRpcError",
+    "RpcResponse",
+    "SignatureStatusResponse",
+    "TOKEN_721_PROGRAM_ID",
+    "WALLET_PERMISSIONS_PROGRAM_ID",
+    "WalletPermissionAccount",
+    "MetadataAttributeInput",
+    "Token721MetadataInput",
+    "get_token_721_collection",
+    "get_token_721_token",
+    "get_wallet_permission_account",
+    "build_initialize_collection_instruction",
+    "build_mint_nft_instruction",
+    "build_transfer_nft_instruction",
+    "build_update_metadata_instruction",
+    "build_initialize_wallet_permissions_instruction",
+    "build_freeze_wallet_instruction",
+]

aeko_sdk-0.1.0/src/aeko_sdk/accounts.py

@@ -0,0 +1,255 @@
+from __future__ import annotations
+
+from base64 import b64decode
+from dataclasses import dataclass
+from typing import Any
+
+from .base58 import b58encode
+from .borsh import BorshReader
+from .client import AekoClient
+
+TOKEN_721_PROGRAM_ID = b58encode(bytes([10] * 32))
+WALLET_PERMISSIONS_PROGRAM_ID = b58encode(bytes([10] * 32))
+
+
+@dataclass(slots=True)
+class MetadataAttribute:
+    trait_type: str
+    value: str
+
+
+@dataclass(slots=True)
+class Token721Metadata:
+    name: str
+    description: str | None
+    uri: str
+    image_uri: str | None
+    attributes: list[MetadataAttribute]
+
+
+@dataclass(slots=True)
+class Token721Collection:
+    authority: str
+    name: str
+    symbol: str
+    base_uri: str | None
+    total_minted: int
+    is_initialized: bool
+
+
+@dataclass(slots=True)
+class Token721Token:
+    collection: str
+    token_id: int
+    owner: str
+    creator: str
+    royalty_bps: int
+    metadata: Token721Metadata
+    frozen: bool
+    is_initialized: bool
+
+
+@dataclass(slots=True)
+class TokenSpendCap:
+    mint: str
+    max_single_tx: int | None
+    max_daily: int | None
+
+
+@dataclass(slots=True)
+class SpendLimitPolicy:
+    max_single_tx_aeko: int | None
+    max_daily_aeko: int | None
+    token_caps: list[TokenSpendCap]
+
+
+@dataclass(slots=True)
+class DelegatePermission:
+    delegate: str
+    role: str
+    label: str | None
+    status: str
+    valid_from_epoch: int
+    valid_until_epoch: int | None
+    spend_limit: SpendLimitPolicy
+    program_allowlist: list[str]
+    token_allowlist: list[str]
+    app_scope_hashes: list[str]
+    requires_reauth: bool
+    last_used_epoch: int | None
+    last_used_slot: int | None
+
+
+@dataclass(slots=True)
+class WalletPermissionAccount:
+    wallet: str
+    did: str
+    version: int
+    policy_nonce: int
+    is_frozen: bool
+    freeze_reason_code: int | None
+    reauth_required_until_epoch: int | None
+    owner: str
+    delegates: list[DelegatePermission]
+    default_program_policy: str
+    created_at_epoch: int
+    updated_at_epoch: int
+    is_initialized: bool
+
+
+def _decode_account_bytes(account_info: dict[str, Any]) -> bytes:
+    raw_data = account_info["data"]
+    encoded = raw_data[0] if isinstance(raw_data, list) else raw_data
+    return b64decode(encoded)
+
+
+def _decode_metadata(reader: BorshReader) -> Token721Metadata:
+    return Token721Metadata(
+        name=reader.read_string(),
+        description=reader.read_option_string(),
+        uri=reader.read_string(),
+        image_uri=reader.read_option_string(),
+        attributes=reader.read_vec(
+            lambda: MetadataAttribute(
+                trait_type=reader.read_string(),
+                value=reader.read_string(),
+            )
+        ),
+    )
+
+
+def decode_token_721_collection(account_info: dict[str, Any]) -> Token721Collection:
+    reader = BorshReader(_decode_account_bytes(account_info))
+    return Token721Collection(
+        authority=reader.read_pubkey(),
+        name=reader.read_string(),
+        symbol=reader.read_string(),
+        base_uri=reader.read_option_string(),
+        total_minted=reader.read_u64(),
+        is_initialized=reader.read_bool(),
+    )
+
+
+def decode_token_721_token(account_info: dict[str, Any]) -> Token721Token:
+    reader = BorshReader(_decode_account_bytes(account_info))
+    return Token721Token(
+        collection=reader.read_pubkey(),
+        token_id=reader.read_u64(),
+        owner=reader.read_pubkey(),
+        creator=reader.read_pubkey(),
+        royalty_bps=reader.read_u16(),
+        metadata=_decode_metadata(reader),
+        frozen=reader.read_bool(),
+        is_initialized=reader.read_bool(),
+    )
+
+
+def _read_permission_role(value: int) -> str:
+    return ["owner", "spender", "viewer"][value]
+
+
+def _read_permission_status(value: int) -> str:
+    return ["active", "revoked", "expired", "frozen"][value]
+
+
+def _read_program_policy_mode(value: int) -> str:
+    return ["deny_by_default", "allow_by_default"][value]
+
+
+def _decode_spend_limit_policy(reader: BorshReader) -> SpendLimitPolicy:
+    return SpendLimitPolicy(
+        max_single_tx_aeko=reader.read_option_u64(),
+        max_daily_aeko=reader.read_option_u64(),
+        token_caps=reader.read_vec(
+            lambda: TokenSpendCap(
+                mint=reader.read_pubkey(),
+                max_single_tx=reader.read_option_u64(),
+                max_daily=reader.read_option_u64(),
+            )
+        ),
+    )
+
+
+def decode_wallet_permission_account(account_info: dict[str, Any]) -> WalletPermissionAccount:
+    reader = BorshReader(_decode_account_bytes(account_info))
+    wallet = reader.read_pubkey()
+    did = reader.read_string()
+    version = reader.read_u8()
+    policy_nonce = reader.read_u64()
+    is_frozen = reader.read_bool()
+    freeze_reason_code = reader.read_option_u16()
+    reauth_required_until_epoch = reader.read_option_u64()
+    owner = reader.read_pubkey()
+    delegates = reader.read_vec(
+        lambda: DelegatePermission(
+            delegate=reader.read_pubkey(),
+            role=_read_permission_role(reader.read_u8()),
+            label=reader.read_option_string(),
+            status=_read_permission_status(reader.read_u8()),
+            valid_from_epoch=reader.read_u64(),
+            valid_until_epoch=reader.read_option_u64(),
+            spend_limit=_decode_spend_limit_policy(reader),
+            program_allowlist=reader.read_vec(reader.read_pubkey),
+            token_allowlist=reader.read_vec(reader.read_pubkey),
+            app_scope_hashes=reader.read_vec(lambda: reader._take(32).hex()),
+            requires_reauth=reader.read_bool(),
+            last_used_epoch=reader.read_option_u64(),
+            last_used_slot=reader.read_option_u64(),
+        )
+    )
+    reader.read_vec(  # usage windows, currently skipped in the public Python view
+        lambda: (
+            reader.read_pubkey(),
+            reader.read_u64(),
+            reader.read_u64(),
+            reader.read_vec(lambda: (reader.read_pubkey(), reader.read_u64())),
+        )
+    )
+    default_program_policy = _read_program_policy_mode(reader.read_u8())
+    created_at_epoch = reader.read_u64()
+    updated_at_epoch = reader.read_u64()
+    is_initialized = reader.read_bool()
+    return WalletPermissionAccount(
+        wallet=wallet,
+        did=did,
+        version=version,
+        policy_nonce=policy_nonce,
+        is_frozen=is_frozen,
+        freeze_reason_code=freeze_reason_code,
+        reauth_required_until_epoch=reauth_required_until_epoch,
+        owner=owner,
+        delegates=delegates,
+        default_program_policy=default_program_policy,
+        created_at_epoch=created_at_epoch,
+        updated_at_epoch=updated_at_epoch,
+        is_initialized=is_initialized,
+    )
+
+
+def get_token_721_collection(client: AekoClient, account: str) -> Token721Collection:
+    info = client.get_account_info(account)
+    if info is None:
+        raise ValueError(f"Collection account {account} was not found.")
+    if info["owner"] != TOKEN_721_PROGRAM_ID:
+        raise ValueError(f"Collection account {account} is not owned by the AEKO-721 program.")
+    return decode_token_721_collection(info)
+
+
+def get_token_721_token(client: AekoClient, account: str) -> Token721Token:
+    info = client.get_account_info(account)
+    if info is None:
+        raise ValueError(f"Token account {account} was not found.")
+    if info["owner"] != TOKEN_721_PROGRAM_ID:
+        raise ValueError(f"Token account {account} is not owned by the AEKO-721 program.")
+    return decode_token_721_token(info)
+
+
+def get_wallet_permission_account(client: AekoClient, account: str) -> WalletPermissionAccount:
+    info = client.get_account_info(account)
+    if info is None:
+        raise ValueError(f"Wallet permission account {account} was not found.")
+    if info["owner"] != WALLET_PERMISSIONS_PROGRAM_ID:
+        raise ValueError(
+            f"Wallet permission account {account} is not owned by the wallet-permissions program."
+        )
+    return decode_wallet_permission_account(info)

aeko_sdk-0.1.0/src/aeko_sdk/base58.py

@@ -0,0 +1,24 @@
+ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+ALPHABET_INDEX = {char: index for index, char in enumerate(ALPHABET)}
+
+
+def b58encode(data: bytes) -> str:
+    number = int.from_bytes(data, "big")
+    encoded = ""
+
+    while number > 0:
+        number, remainder = divmod(number, 58)
+        encoded = ALPHABET[remainder] + encoded
+
+    leading_zeroes = len(data) - len(data.lstrip(b"\x00"))
+    return ("1" * leading_zeroes) + (encoded or "")
+
+
+def b58decode(value: str) -> bytes:
+    number = 0
+    for char in value:
+        number = number * 58 + ALPHABET_INDEX[char]
+
+    decoded = b"" if number == 0 else number.to_bytes((number.bit_length() + 7) // 8, "big")
+    leading_zeroes = len(value) - len(value.lstrip("1"))
+    return (b"\x00" * leading_zeroes) + decoded

aeko_sdk-0.1.0/src/aeko_sdk/borsh.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .base58 import b58encode
+
+
+@dataclass
+class BorshReader:
+    data: bytes
+    offset: int = 0
+
+    def _take(self, length: int) -> bytes:
+        next_offset = self.offset + length
+        if next_offset > len(self.data):
+            raise ValueError("Borsh payload ended unexpectedly.")
+        chunk = self.data[self.offset:next_offset]
+        self.offset = next_offset
+        return chunk
+
+    def read_u8(self) -> int:
+        return self._take(1)[0]
+
+    def read_u16(self) -> int:
+        return int.from_bytes(self._take(2), "little")
+
+    def read_u32(self) -> int:
+        return int.from_bytes(self._take(4), "little")
+
+    def read_u64(self) -> int:
+        return int.from_bytes(self._take(8), "little")
+
+    def read_bool(self) -> bool:
+        return self.read_u8() == 1
+
+    def read_pubkey(self) -> str:
+        return b58encode(self._take(32))
+
+    def read_string(self) -> str:
+        return self._take(self.read_u32()).decode("utf-8")
+
+    def read_option_string(self) -> str | None:
+        return self.read_string() if self.read_u8() == 1 else None
+
+    def read_option_u64(self) -> int | None:
+        return self.read_u64() if self.read_u8() == 1 else None
+
+    def read_option_u16(self) -> int | None:
+        return self.read_u16() if self.read_u8() == 1 else None
+
+    def read_vec(self, item_reader):
+        length = self.read_u32()
+        return [item_reader() for _ in range(length)]

aeko_sdk-0.1.0/src/aeko_sdk/builders.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+from base64 import b64encode
+from dataclasses import dataclass
+
+from .accounts import TOKEN_721_PROGRAM_ID, WALLET_PERMISSIONS_PROGRAM_ID
+from .base58 import b58decode
+
+
+def _encode_u8(value: int) -> bytes:
+    return value.to_bytes(1, "little")
+
+
+def _encode_u16(value: int) -> bytes:
+    return value.to_bytes(2, "little")
+
+
+def _encode_u32(value: int) -> bytes:
+    return value.to_bytes(4, "little")
+
+
+def _encode_u64(value: int) -> bytes:
+    return value.to_bytes(8, "little")
+
+
+def _encode_bool(value: bool) -> bytes:
+    return _encode_u8(1 if value else 0)
+
+
+def _encode_string(value: str) -> bytes:
+    encoded = value.encode("utf-8")
+    return _encode_u32(len(encoded)) + encoded
+
+
+def _encode_option_string(value: str | None) -> bytes:
+    return b"\x00" if value is None else b"\x01" + _encode_string(value)
+
+
+def _encode_option_u64(value: int | None) -> bytes:
+    return b"\x00" if value is None else b"\x01" + _encode_u64(value)
+
+
+def _encode_pubkey(value: str) -> bytes:
+    return b58decode(value)
+
+
+def _encode_vec(items: list, encoder) -> bytes:
+    return _encode_u32(len(items)) + b"".join(encoder(item) for item in items)
+
+
+def _encode_metadata(metadata: "Token721MetadataInput") -> bytes:
+    return (
+        _encode_string(metadata.name)
+        + _encode_option_string(metadata.description)
+        + _encode_string(metadata.uri)
+        + _encode_option_string(metadata.image_uri)
+        + _encode_vec(metadata.attributes, lambda item: _encode_string(item.trait_type) + _encode_string(item.value))
+    )
+
+
+@dataclass(slots=True)
+class InstructionAccount:
+    pubkey: str
+    is_signer: bool
+    is_writable: bool
+
+
+@dataclass(slots=True)
+class MetadataAttributeInput:
+    trait_type: str
+    value: str
+
+
+@dataclass(slots=True)
+class Token721MetadataInput:
+    name: str
+    uri: str
+    description: str | None = None
+    image_uri: str | None = None
+    attributes: list[MetadataAttributeInput] | None = None
+
+
+def _instruction(program_id: str, accounts: list[InstructionAccount], data: bytes) -> dict:
+    return {
+        "programId": program_id,
+        "accounts": [
+            {
+                "pubkey": account.pubkey,
+                "isSigner": account.is_signer,
+                "isWritable": account.is_writable,
+            }
+            for account in accounts
+        ],
+        "dataBase64": b64encode(data).decode("utf-8"),
+    }
+
+
+def build_initialize_collection_instruction(
+    *,
+    collection: str,
+    authority: str,
+    name: str,
+    symbol: str,
+    base_uri: str | None = None,
+    program_id: str = TOKEN_721_PROGRAM_ID,
+) -> dict:
+    data = _encode_u8(0) + _encode_string(name) + _encode_string(symbol) + _encode_option_string(base_uri)
+    return _instruction(
+        program_id,
+        [
+            InstructionAccount(collection, False, True),
+            InstructionAccount(authority, True, True),
+        ],
+        data,
+    )
+
+
+def build_mint_nft_instruction(
+    *,
+    collection: str,
+    token: str,
+    authority: str,
+    token_id: int,
+    owner: str,
+    creator: str,
+    royalty_bps: int,
+    metadata: Token721MetadataInput,
+    program_id: str = TOKEN_721_PROGRAM_ID,
+) -> dict:
+    attributes = metadata.attributes or []
+    metadata_bytes = _encode_metadata(
+        Token721MetadataInput(
+            name=metadata.name,
+            description=metadata.description,
+            uri=metadata.uri,
+            image_uri=metadata.image_uri,
+            attributes=attributes,
+        )
+    )
+    data = (
+        _encode_u8(1)
+        + _encode_u64(token_id)
+        + _encode_pubkey(owner)
+        + _encode_pubkey(creator)
+        + _encode_u16(royalty_bps)
+        + metadata_bytes
+    )
+    return _instruction(
+        program_id,
+        [
+            InstructionAccount(collection, False, True),
+            InstructionAccount(token, False, True),
+            InstructionAccount(authority, True, False),
+        ],
+        data,
+    )
+
+
+def build_transfer_nft_instruction(
+    *,
+    token: str,
+    owner: str,
+    new_owner: str,
+    program_id: str = TOKEN_721_PROGRAM_ID,
+) -> dict:
+    return _instruction(
+        program_id,
+        [
+            InstructionAccount(token, False, True),
+            InstructionAccount(owner, True, False),
+        ],
+        _encode_u8(4) + _encode_pubkey(new_owner),
+    )
+
+
+def build_update_metadata_instruction(
+    *,
+    token: str,
+    authority: str,
+    metadata: Token721MetadataInput,
+    program_id: str = TOKEN_721_PROGRAM_ID,
+) -> dict:
+    return _instruction(
+        program_id,
+        [
+            InstructionAccount(token, False, True),
+            InstructionAccount(authority, True, False),
+        ],
+        _encode_u8(5)
+        + _encode_metadata(
+            Token721MetadataInput(
+                name=metadata.name,
+                description=metadata.description,
+                uri=metadata.uri,
+                image_uri=metadata.image_uri,
+                attributes=metadata.attributes or [],
+            )
+        ),
+    )
+
+
+def build_initialize_wallet_permissions_instruction(
+    *,
+    permission_state: str,
+    audit_log: str,
+    owner: str,
+    wallet: str,
+    did: str,
+    current_epoch: int,
+    default_program_policy: int,
+    program_id: str = WALLET_PERMISSIONS_PROGRAM_ID,
+) -> dict:
+    data = (
+        _encode_u8(0)
+        + _encode_pubkey(wallet)
+        + _encode_string(did)
+        + _encode_u64(current_epoch)
+        + _encode_u8(default_program_policy)
+    )
+    return _instruction(
+        program_id,
+        [
+            InstructionAccount(permission_state, False, True),
+            InstructionAccount(audit_log, False, True),
+            InstructionAccount(owner, True, False),
+        ],
+        data,
+    )
+
+
+def build_freeze_wallet_instruction(
+    *,
+    permission_state: str,
+    audit_log: str,
+    owner: str,
+    reason_code: int | None,
+    reauth_required_until_epoch: int | None,
+    current_epoch: int,
+    current_slot: int,
+    program_id: str = WALLET_PERMISSIONS_PROGRAM_ID,
+) -> dict:
+    reason_bytes = b"\x00" if reason_code is None else b"\x01" + _encode_u16(reason_code)
+    data = (
+        _encode_u8(4)
+        + reason_bytes
+        + _encode_option_u64(reauth_required_until_epoch)
+        + _encode_u64(current_epoch)
+        + _encode_u64(current_slot)
+    )
+    return _instruction(
+        program_id,
+        [
+            InstructionAccount(permission_state, False, True),
+            InstructionAccount(audit_log, False, True),
+            InstructionAccount(owner, True, False),
+        ],
+        data,
+    )

aeko_sdk-0.1.0/src/aeko_sdk/client.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import json
+from base64 import b64encode
+from itertools import count
+from typing import Any
+from urllib import request
+
+from .errors import AekoRpcError
+from .types import RpcResponse, SignatureStatusResponse
+
+
+class AekoClient:
+    def __init__(self, rpc_url: str, *, timeout: float = 30.0) -> None:
+        self.rpc_url = rpc_url
+        self.timeout = timeout
+        self._id_counter = count(1)
+
+    def rpc(self, method: str, params: list[Any] | None = None) -> Any:
+        body = {
+            "jsonrpc": "2.0",
+            "id": next(self._id_counter),
+            "method": method,
+            "params": params or [],
+        }
+        raw_body = json.dumps(body).encode("utf-8")
+        http_request = request.Request(
+            self.rpc_url,
+            data=raw_body,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with request.urlopen(http_request, timeout=self.timeout) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+
+        if "error" in payload:
+            error = payload["error"]
+            raise AekoRpcError(
+                error.get("message", "AEKO RPC request failed"),
+                code=error.get("code"),
+                data=error.get("data"),
+            )
+
+        parsed = RpcResponse(
+            jsonrpc=payload.get("jsonrpc", "2.0"),
+            id=payload.get("id", 0),
+            result=payload.get("result"),
+        )
+        return parsed.result
+
+    def get_latest_blockhash(self) -> str:
+        result = self.rpc("getLatestBlockhash")
+        return result["value"]["blockhash"]
+
+    def get_balance(self, pubkey: str) -> int:
+        result = self.rpc("getBalance", [pubkey])
+        return int(result["value"])
+
+    def get_account_info(
+        self,
+        pubkey: str,
+        *,
+        encoding: str = "base64",
+    ) -> dict[str, Any] | None:
+        result = self.rpc("getAccountInfo", [pubkey, {"encoding": encoding}])
+        return result["value"]
+
+    def get_program_accounts(
+        self,
+        program_id: str,
+        *,
+        encoding: str = "base64",
+        filters: list[dict[str, Any]] | None = None,
+    ) -> list[dict[str, Any]]:
+        config: dict[str, Any] = {"encoding": encoding}
+        if filters:
+            config["filters"] = filters
+        return self.rpc("getProgramAccounts", [program_id, config])
+
+    def send_transaction(self, transaction_bytes: bytes, *, encoding: str = "base64") -> str:
+        encoded = (
+            transaction_bytes.decode("utf-8")
+            if encoding == "base64" and _looks_like_text(transaction_bytes)
+            else b64encode(transaction_bytes).decode("utf-8")
+        )
+        return self.rpc("sendTransaction", [encoded, {"encoding": encoding}])
+
+    def get_signature_statuses(
+        self, signatures: list[str]
+    ) -> list[SignatureStatusResponse | None]:
+        result = self.rpc("getSignatureStatuses", [signatures])
+        statuses = []
+        for item in result["value"]:
+            if item is None:
+                statuses.append(None)
+                continue
+            statuses.append(
+                SignatureStatusResponse(
+                    slot=item.get("slot"),
+                    confirmations=item.get("confirmations"),
+                    confirmation_status=item.get("confirmationStatus"),
+                    err=item.get("err"),
+                )
+            )
+        return statuses
+
+
+def _looks_like_text(value: bytes) -> bool:
+    try:
+        value.decode("utf-8")
+    except UnicodeDecodeError:
+        return False
+    return True

aeko_sdk-0.1.0/src/aeko_sdk/errors.py

@@ -0,0 +1,7 @@
+class AekoRpcError(Exception):
+    """Raised when an AEKO RPC request returns an error payload."""
+
+    def __init__(self, message: str, *, code: int | None = None, data: object | None = None):
+        super().__init__(message)
+        self.code = code
+        self.data = data

aeko_sdk-0.1.0/src/aeko_sdk/types.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class RpcResponse:
+    jsonrpc: str
+    id: int
+    result: Any
+
+
+@dataclass(slots=True)
+class SignatureStatusResponse:
+    slot: int | None
+    confirmations: int | None
+    confirmation_status: str | None
+    err: Any

aeko_sdk-0.1.0/src/aeko_sdk.egg-info/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: aeko-sdk
+Version: 0.1.0
+Summary: AEKO Chain Python SDK
+Author-email: AEKO Chain Maintainers <maintainers@aeko.chain>
+License: Apache-2.0
+Project-URL: Homepage, https://chain.aeko.social/
+Project-URL: Repository, https://github.com/MilliHub-dev/aeko-chain
+Project-URL: Documentation, https://github.com/MilliHub-dev/aeko-chain/tree/main/sdk/python
+Keywords: aeko,blockchain,python,sdk,rpc
+Classifier: Development Status :: 3 - Alpha
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# AEKO Python SDK
+
+`aeko-sdk` is the Python SDK for AEKO Chain scripting, automation, analytics, and operational tooling.
+
+Current scope:
+
+- JSON-RPC connection wrapper
+- account and balance queries
+- transaction submit and signature status queries
+- AEKO-721 account decoders and instruction builders
+- wallet-permissions account decoder and instruction builders
+- lightweight helpers for analytics and monitoring scripts
+
+Examples:
+
+- [`examples/basic_usage.py`](/Users/ok/Documents/projects/aeko-chain/sdk/python/examples/basic_usage.py)
+- [`examples/account_watch.py`](/Users/ok/Documents/projects/aeko-chain/sdk/python/examples/account_watch.py)
+
+## Local Verification
+
+```bash
+python3 -m compileall sdk/python/src sdk/python/examples
+```
+
+## Local Install
+
+```bash
+pip install -e sdk/python
+```

aeko_sdk-0.1.0/src/aeko_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+src/aeko_sdk/__init__.py
+src/aeko_sdk/accounts.py
+src/aeko_sdk/base58.py
+src/aeko_sdk/borsh.py
+src/aeko_sdk/builders.py
+src/aeko_sdk/client.py
+src/aeko_sdk/errors.py
+src/aeko_sdk/types.py
+src/aeko_sdk.egg-info/PKG-INFO
+src/aeko_sdk.egg-info/SOURCES.txt
+src/aeko_sdk.egg-info/dependency_links.txt
+src/aeko_sdk.egg-info/top_level.txt

aeko_sdk-0.1.0/src/aeko_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aeko_sdk-0.1.0/src/aeko_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+aeko_sdk