arete-sdk 0.11.0__py3-none-any.whl

arete/__init__.py

@@ -0,0 +1,310 @@
+"""Arete Python SDK — idiomatic Python projection of the Arete core SDK API.
+
+See docs/internal/sdk-core-api.md (canonical surface) and
+docs/internal/sdk-python-alignment.md (Python projection).
+
+    import arete
+    a4 = await arete.Arete.connect(STACK, wallet=wallet)
+    async for round in a4.views.ore_round.latest.use(take=10):
+        ...
+"""
+
+from __future__ import annotations
+
+__version__ = "0.4.0"
+
+
+class _Unset:
+    """Sentinel distinguishing "no active subscription" from an empty result."""
+
+    _instance = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "arete.UNSET"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+UNSET = _Unset()
+
+# NOTE: UNSET must exist before the submodule imports below (arete.views
+# imports it at module load).
+
+from arete.errors import (  # noqa: E402
+    AreteConnectionError,
+    AreteError,
+    AuthError,
+    HttpRequestError,
+    ProcessedSlotTimeoutError,
+    SubscriptionError,
+)
+from arete.auth import AuthConfig  # noqa: E402
+from arete.wire import RichUpdate, Update  # noqa: E402
+from arete.views import (  # noqa: E402
+    DEFAULT_INITIAL_DATA_TIMEOUT,
+    InitialDataTimeoutError,
+    ListViewHandle,
+    StateViewHandle,
+    ViewDef,
+    ViewsNamespace,
+)
+from arete.chain import (  # noqa: E402
+    ChainClient,
+    ChainClock,
+    ChainError,
+    HttpChainClient,
+    MintAccountInfo,
+    NativeBalanceInfo,
+    RawAccountInfo,
+    TokenAccountInfo,
+    TokenBalanceInfo,
+)
+from arete.transactions import (  # noqa: E402
+    HttpTransactionTransport,
+    TransactionTransport,
+    TransactionTransportError,
+)
+from arete.gateway import (  # noqa: E402
+    HostedSolanaGatewayBindings,
+    create_hosted_solana_gateway_transports,
+)
+from arete.amounts import (  # noqa: E402
+    format_raw_to_ui,
+    get_mint_decimals,
+    parse_ui_amount_to_raw,
+    resolve_amount,
+    resolve_amount_to_raw,
+    resolve_amounts_to_raw,
+    to_raw_amount,
+)
+from arete.spl import (  # noqa: E402
+    ASSOCIATED_TOKEN_PROGRAM_ADDRESS,
+    SPL_TOKEN_PROGRAM_ADDRESS,
+    SYSTEM_PROGRAM_ADDRESS,
+    TOKEN_2022_PROGRAM_ADDRESS,
+    derive_associated_token_account,
+    resolve_token_program_address,
+)
+from arete.instructions import (  # noqa: E402
+    BuiltAccountMeta,
+    BuiltInstruction,
+    ErrorMetadata,
+    InstructionError,
+    InstructionHandler,
+    PdaConfig,
+    derive_pda,
+    find_program_address,
+    format_program_error,
+    parse_program_error,
+)
+from arete.read import (  # noqa: E402
+    AccountBatchItem,
+    AccountBatchResult,
+    AccountReader,
+    ProgramAccountReadDef,
+    ProgramQueryDef,
+    ReadRequestError,
+    StackQueryDef,
+)
+from arete.program_read_transport import (  # noqa: E402
+    ProgramReadDescriptor,
+    ProgramReleaseReference,
+    validate_program_read_descriptor,
+)
+from arete.wallet import (  # noqa: E402
+    ConfirmedTransactionOutcome,
+    SendOptions,
+    SendResult,
+    TransactionFailureOutcome,
+    TransactionInspectionResult,
+    WalletAdapter,
+    WalletError,
+    WalletExecutionContext,
+)
+from arete.operations import (  # noqa: E402
+    OperationCallbackError,
+    OperationExecutionError,
+    OperationReceipt,
+    OperationTransactionReceipt,
+    PreparedFlow,
+    PreparedInstruction,
+    PreparedOperation,
+    PreparedTransaction,
+    PreparedTransactionBody,
+    SignerRegistry,
+    TransactionExecutionError,
+    append_flow_transactions,
+    append_transaction_instructions,
+    create_prepared_flow,
+    create_prepared_instruction,
+    create_prepared_transaction,
+    create_prepared_transaction_body,
+    create_signer_registry,
+    describe_prepared_operation,
+    execute_prepared_operation,
+    format_prepared_operation,
+    get_transaction_failure_outcome,
+    inspect_prepared_operation,
+    prepend_flow_transaction_instructions,
+    prepend_transaction_instructions,
+    unwrap_operation_execution_error,
+)
+from arete.stack import (  # noqa: E402
+    ConnectedProgram,
+    Operation,
+    ProgramDef,
+    ProgramOperationContext,
+    ProgramOperations,
+    StackDef,
+    StackEndpoints,
+    flow_operation,
+    instruction_operation,
+    transaction_operation,
+    with_programs,
+)
+from arete.extensions import (  # noqa: E402
+    apply_connected_stack_extensions,
+    extend_program,
+    extend_programs,
+    extend_stack,
+)
+from arete.client import Arete  # noqa: E402
+from arete.session import Session, SessionError, create_session  # noqa: E402
+
+__all__ = [
+    "UNSET",
+    "__version__",
+    # client & session
+    "Arete",
+    "Session",
+    "SessionError",
+    "create_session",
+    # errors
+    "AreteError",
+    "AreteConnectionError",
+    "AuthError",
+    "ChainError",
+    "HttpRequestError",
+    "InitialDataTimeoutError",
+    "InstructionError",
+    "OperationCallbackError",
+    "OperationExecutionError",
+    "ProcessedSlotTimeoutError",
+    "ReadRequestError",
+    "SubscriptionError",
+    "TransactionExecutionError",
+    "TransactionTransportError",
+    "WalletError",
+    # auth
+    "AuthConfig",
+    # views & updates
+    "Update",
+    "RichUpdate",
+    "ViewDef",
+    "ViewsNamespace",
+    "DEFAULT_INITIAL_DATA_TIMEOUT",
+    "ListViewHandle",
+    "StateViewHandle",
+    # stack binding model
+    "StackDef",
+    "StackEndpoints",
+    "ProgramDef",
+    "ProgramOperations",
+    "ProgramOperationContext",
+    "ConnectedProgram",
+    "with_programs",
+    # extensions
+    "extend_stack",
+    "extend_program",
+    "extend_programs",
+    "apply_connected_stack_extensions",
+    "Operation",
+    "instruction_operation",
+    "transaction_operation",
+    "flow_operation",
+    # wallet & outcomes
+    "WalletAdapter",
+    "WalletExecutionContext",
+    "SendOptions",
+    "SendResult",
+    "TransactionInspectionResult",
+    "ConfirmedTransactionOutcome",
+    "TransactionFailureOutcome",
+    "get_transaction_failure_outcome",
+    # prepared operations
+    "PreparedInstruction",
+    "PreparedTransaction",
+    "PreparedFlow",
+    "PreparedOperation",
+    "PreparedTransactionBody",
+    "create_prepared_instruction",
+    "create_prepared_transaction",
+    "create_prepared_flow",
+    "create_prepared_transaction_body",
+    "prepend_transaction_instructions",
+    "append_transaction_instructions",
+    "append_flow_transactions",
+    "prepend_flow_transaction_instructions",
+    "execute_prepared_operation",
+    "inspect_prepared_operation",
+    "describe_prepared_operation",
+    "format_prepared_operation",
+    "unwrap_operation_execution_error",
+    "OperationReceipt",
+    "OperationTransactionReceipt",
+    "SignerRegistry",
+    "create_signer_registry",
+    # chain & transactions
+    "ChainClient",
+    "HttpChainClient",
+    "ChainClock",
+    "RawAccountInfo",
+    "MintAccountInfo",
+    "TokenAccountInfo",
+    "TokenBalanceInfo",
+    "NativeBalanceInfo",
+    "TransactionTransport",
+    "HttpTransactionTransport",
+    "HostedSolanaGatewayBindings",
+    "create_hosted_solana_gateway_transports",
+    # amounts & SPL
+    "parse_ui_amount_to_raw",
+    "format_raw_to_ui",
+    "to_raw_amount",
+    "get_mint_decimals",
+    "resolve_amount",
+    "resolve_amount_to_raw",
+    "resolve_amounts_to_raw",
+    "SPL_TOKEN_PROGRAM_ADDRESS",
+    "TOKEN_2022_PROGRAM_ADDRESS",
+    "ASSOCIATED_TOKEN_PROGRAM_ADDRESS",
+    "SYSTEM_PROGRAM_ADDRESS",
+    "derive_associated_token_account",
+    "resolve_token_program_address",
+    # instruction runtime
+    "InstructionHandler",
+    "BuiltInstruction",
+    "BuiltAccountMeta",
+    "ErrorMetadata",
+    "PdaConfig",
+    "derive_pda",
+    "find_program_address",
+    "parse_program_error",
+    "format_program_error",
+    # program reads
+    "AccountReader",
+    "AccountBatchItem",
+    "AccountBatchResult",
+    "ProgramAccountReadDef",
+    "ProgramQueryDef",
+    "StackQueryDef",
+    "ProgramReadDescriptor",
+    "ProgramReleaseReference",
+    "validate_program_read_descriptor",
+]

arete/amounts.py

@@ -0,0 +1,157 @@
+"""Token amount helpers (port of ``typescript/core/src/amounts.ts``).
+
+An :data:`AmountInput` is either raw base units (a bare ``int``, or
+``{"raw": int | str}``) or UI units (``{"ui": str | int | float}``). UI
+parsing is exact string math pinned to the mint's decimals — no float
+precision loss. Decimals are fetched from the chain read endpoint only when
+they are unknown and actually needed.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, Optional, Union
+
+from arete.chain import ChainClient
+
+AmountInput = Union[int, Mapping[str, Any]]
+
+_UI_AMOUNT_RE = re.compile(r"^\d+(?:\.\d+)?$")
+
+
+@dataclass(frozen=True)
+class ResolvedAmount:
+    raw: int
+    decimals: int
+
+
+def parse_ui_amount_to_raw(value: Union[str, int, float], decimals: int) -> int:
+    """Convert a UI amount ("1.5") to raw base units using string math."""
+    trimmed = str(value).strip()
+    if not _UI_AMOUNT_RE.match(trimmed):
+        raise ValueError(f"Invalid UI amount: {value}")
+
+    whole_part, _, fraction_part = trimmed.partition(".")
+    if len(fraction_part) > decimals:
+        excess = fraction_part[decimals:]
+        if any(ch != "0" for ch in excess):
+            raise ValueError(
+                f"UI amount {value} has more fractional digits than the mint's "
+                f"{decimals} decimals"
+            )
+    fraction = fraction_part.ljust(decimals, "0")[:decimals]
+    whole = int(whole_part or "0") * 10**decimals
+    return whole + int(fraction or "0")
+
+
+def format_raw_to_ui(raw: Union[int, str], decimals: int) -> str:
+    """Format raw base units as a UI decimal string (inverse of
+    :func:`parse_ui_amount_to_raw`)."""
+    value = _to_int(raw, "raw amount")
+    negative = value < 0
+    magnitude = -value if negative else value
+    scale = 10**decimals
+    whole, fraction = divmod(magnitude, scale)
+    sign = "-" if negative else ""
+    if decimals == 0 or fraction == 0:
+        return f"{sign}{whole}"
+    fraction_text = str(fraction).rjust(decimals, "0").rstrip("0")
+    return f"{sign}{whole}.{fraction_text}"
+
+
+def _to_int(value: Any, name: str) -> int:
+    if isinstance(value, bool):
+        raise ValueError(f"Invalid {name}: {value!r}")
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        text = value.strip()
+        if re.match(r"^-?\d+$", text):
+            return int(text)
+    raise ValueError(f"Invalid {name}: {value!r}")
+
+
+def _is_raw_input(amount: AmountInput) -> bool:
+    return isinstance(amount, int) or (
+        isinstance(amount, Mapping) and "raw" in amount
+    )
+
+
+def to_raw_amount(amount: AmountInput, decimals: int) -> int:
+    """Resolve an :data:`AmountInput` to raw base units with known decimals."""
+    if isinstance(amount, bool):
+        raise ValueError(f"Invalid amount input: {amount!r}")
+    if isinstance(amount, int):
+        return amount
+    if isinstance(amount, Mapping):
+        if "raw" in amount:
+            return _to_int(amount["raw"], "raw amount")
+        if "ui" in amount:
+            return parse_ui_amount_to_raw(amount["ui"], decimals)
+    raise ValueError(f"Invalid amount input: {amount!r}")
+
+
+async def get_mint_decimals(chain: ChainClient, mint: str) -> int:
+    """Fetch a mint's decimals via the chain read endpoint, raising when
+    unavailable."""
+    account = await chain.mint(mint)
+    if account is None or account.decimals is None:
+        raise ValueError(
+            f"Mint {mint} is missing decimals on the configured read endpoint."
+        )
+    return account.decimals
+
+
+async def resolve_amount(
+    chain: ChainClient,
+    *,
+    mint: str,
+    amount: AmountInput,
+    decimals: Optional[int] = None,
+) -> ResolvedAmount:
+    """Resolve an :data:`AmountInput` to raw base units, fetching the mint's
+    decimals only when they are unknown (a bare int or ``{"raw"}`` input with
+    explicit ``decimals`` never touches the network)."""
+    if _is_raw_input(amount):
+        raw = amount if isinstance(amount, int) else _to_int(amount["raw"], "raw amount")
+        resolved = decimals if decimals is not None else await get_mint_decimals(chain, mint)
+        return ResolvedAmount(raw=raw, decimals=resolved)
+
+    resolved = decimals if decimals is not None else await get_mint_decimals(chain, mint)
+    return ResolvedAmount(raw=to_raw_amount(amount, resolved), decimals=resolved)
+
+
+async def resolve_amount_to_raw(
+    chain: ChainClient,
+    *,
+    mint: str,
+    amount: AmountInput,
+    decimals: Optional[int] = None,
+) -> int:
+    """Resolve an :data:`AmountInput` to raw base units without forcing a
+    decimals fetch when the input is already expressed in raw units."""
+    if isinstance(amount, int) and not isinstance(amount, bool):
+        return amount
+    if isinstance(amount, Mapping) and "raw" in amount:
+        return _to_int(amount["raw"], "raw amount")
+
+    resolved = decimals if decimals is not None else await get_mint_decimals(chain, mint)
+    return to_raw_amount(amount, resolved)
+
+
+async def resolve_amounts_to_raw(
+    chain: ChainClient,
+    inputs: Mapping[str, Mapping[str, Any]],
+) -> Dict[str, int]:
+    """Resolve a named set of amount inputs (each ``{"mint", "amount"[,
+    "decimals"]}``) to raw base units, preserving keys."""
+    resolved: Dict[str, int] = {}
+    for name, entry in inputs.items():
+        resolved[name] = await resolve_amount_to_raw(
+            chain,
+            mint=entry["mint"],
+            amount=entry["amount"],
+            decimals=entry.get("decimals"),
+        )
+    return resolved