meshtrade 1.21.0__py3-none-any.whl → 1.23.0__py3-none-any.whl

meshtrade/ledger/transaction/v1/__init__.py

@@ -28,7 +28,6 @@ from .service_meshpy import (
     TransactionServiceGRPCClient,
     TransactionServiceGRPCClientInterface,
 )
-from .service_options_meshpy import ClientOptions
 
 # ===================================================================
 # END OF AUTO-GENERATED SECTION
@@ -50,7 +49,6 @@ from .service_options_meshpy import ClientOptions
 # Combined auto-generated and manual exports
 __all__ = [
     # Generated exports
-    "ClientOptions",
     "GetTransactionStateRequest",
     "GetTransactionStateResponse",
     "MonitorTransactionStateRequest",

meshtrade/ledger/transaction/v1/service_meshpy.py

@@ -15,7 +15,7 @@ from typing import Optional
 from meshtrade.common import BaseGRPCClient
 from meshtrade.iam.api_user.v1.api_credentials import find_credentials
 
-from .service_options_meshpy import ServiceOptions
+from meshtrade.common.service_options import ServiceOptions
 from .service_pb2 import (
 GetTransactionStateRequest,
 GetTransactionStateResponse,

meshtrade/ledger/transaction/v1/transaction_state_machine.py

@@ -0,0 +1,75 @@
+"""Transaction state machine validation and transition logic.
+
+This module provides state machine functions for transaction states and actions,
+implementing the transaction lifecycle management logic.
+"""
+
+from meshtrade.ledger.transaction.v1.transaction_action_pb2 import TransactionAction
+from meshtrade.ledger.transaction.v1.transaction_state_pb2 import TransactionState
+
+
+def transaction_state_can_perform_action_at_state(state: TransactionState | None, action: TransactionAction | None) -> bool:
+    """Check if the given action can be performed at the current transaction state.
+
+    This implements the state machine logic for transaction lifecycle management.
+
+    State Transitions:
+    - DRAFT -> BUILD/COMMIT -> SIGNING_IN_PROGRESS
+    - SIGNING_IN_PROGRESS -> SIGN/MARK_PENDING -> PENDING
+    - PENDING -> SUBMIT -> SUBMISSION_IN_PROGRESS
+    - SUBMISSION_IN_PROGRESS -> SUBMIT (retry) -> INDETERMINATE or SUCCESS/FAILED
+    - INDETERMINATE -> SUBMIT (retry) -> SUCCESS/FAILED
+    - FAILED/SUCCESSFUL -> No further actions allowed (terminal states)
+
+    Args:
+        state: The current TransactionState (can be None)
+        action: The TransactionAction to perform (can be None)
+
+    Returns:
+        True if the action can be performed at the given state, False otherwise
+
+    None Safety:
+        Returns False if either state or action is None
+
+    Example:
+        >>> transaction_state_can_perform_action_at_state(
+        ...     TransactionState.TRANSACTION_STATE_DRAFT,
+        ...     TransactionAction.TRANSACTION_ACTION_BUILD
+        ... )
+        True
+        >>> transaction_state_can_perform_action_at_state(
+        ...     TransactionState.TRANSACTION_STATE_SUCCESSFUL,
+        ...     TransactionAction.TRANSACTION_ACTION_SUBMIT
+        ... )
+        False
+    """
+    if state is None or action is None:
+        return False
+
+    if state == TransactionState.TRANSACTION_STATE_DRAFT:
+        return action in {
+            TransactionAction.TRANSACTION_ACTION_BUILD,
+            TransactionAction.TRANSACTION_ACTION_COMMIT,
+        }
+
+    elif state == TransactionState.TRANSACTION_STATE_SIGNING_IN_PROGRESS:
+        return action in {
+            TransactionAction.TRANSACTION_ACTION_SIGN,
+            TransactionAction.TRANSACTION_ACTION_MARK_PENDING,
+        }
+
+    elif state in {
+        TransactionState.TRANSACTION_STATE_PENDING,
+        TransactionState.TRANSACTION_STATE_SUBMISSION_IN_PROGRESS,
+        TransactionState.TRANSACTION_STATE_INDETERMINATE,
+    }:
+        return action == TransactionAction.TRANSACTION_ACTION_SUBMIT
+
+    elif state in {
+        TransactionState.TRANSACTION_STATE_FAILED,
+        TransactionState.TRANSACTION_STATE_SUCCESSFUL,
+    }:
+        return False
+
+    else:
+        return False

meshtrade/reporting/account_report/v1/__init__.py

@@ -26,7 +26,6 @@ from .service_meshpy import (
     AccountReportServiceGRPCClient,
     AccountReportServiceGRPCClientInterface,
 )
-from .service_options_meshpy import ClientOptions
 
 # ===================================================================
 # END OF AUTO-GENERATED SECTION
@@ -52,7 +51,6 @@ __all__ = [
     "AccountReportService",
     "AccountReportServiceGRPCClient",
     "AccountReportServiceGRPCClientInterface",
-    "ClientOptions",
     "Disclaimer",
     "FeeEntry",
     "GetAccountReportRequest",

meshtrade/reporting/account_report/v1/income_entry.py

@@ -0,0 +1,35 @@
+"""Income entry utility functions."""
+
+from meshtrade.reporting.account_report.v1.income_entry_pb2 import IncomeNarrative
+
+
+def income_narrative_pretty_string(narrative: IncomeNarrative) -> str:
+    """Generate human-readable string for income narrative.
+
+    Converts enum values to concise, display-friendly strings suitable for
+    reports and user interfaces.
+
+    Args:
+        narrative: IncomeNarrative enum value
+
+    Returns:
+        Pretty-printed string representation:
+        - "-" for unspecified narratives
+        - Descriptive names for known types (e.g., "Yield", "Dividend")
+        - Empty string for unknown values
+    """
+    if narrative == IncomeNarrative.INCOME_NARRATIVE_UNSPECIFIED:
+        return "-"
+    if narrative == IncomeNarrative.INCOME_NARRATIVE_YIELD:
+        return "Yield"
+    if narrative == IncomeNarrative.INCOME_NARRATIVE_DIVIDEND:
+        return "Dividend"
+    if narrative == IncomeNarrative.INCOME_NARRATIVE_INTEREST:
+        return "Interest"
+    if narrative == IncomeNarrative.INCOME_NARRATIVE_PRINCIPAL:
+        return "Principal"
+    if narrative == IncomeNarrative.INCOME_NARRATIVE_DISTRIBUTION:
+        return "Distribution"
+    if narrative == IncomeNarrative.INCOME_NARRATIVE_PROFIT_DISTRIBUTION:
+        return "Profit Distribution"
+    return ""

meshtrade/reporting/account_report/v1/service_meshpy.py

@@ -16,7 +16,7 @@ from meshtrade.common import BaseGRPCClient
 from meshtrade.iam.api_user.v1.api_credentials import find_credentials
 
 from .account_report_pb2 import AccountReport
-from .service_options_meshpy import ServiceOptions
+from meshtrade.common.service_options import ServiceOptions
 from .service_pb2 import (
 GetAccountReportRequest,
 GetExcelAccountReportRequest,

meshtrade/trading/limit_order/v1/__init__.py

@@ -22,7 +22,6 @@ from .service_meshpy import (
     LimitOrderServiceGRPCClient,
     LimitOrderServiceGRPCClientInterface,
 )
-from .service_options_meshpy import ClientOptions
 
 # ===================================================================
 # END OF AUTO-GENERATED SECTION
@@ -44,7 +43,6 @@ from .service_options_meshpy import ClientOptions
 # Combined auto-generated and manual exports
 __all__ = [
     # Generated exports
-    "ClientOptions",
     "GetLimitOrderRequest",
     "LimitOrder",
     "LimitOrderService",

meshtrade/trading/limit_order/v1/service_meshpy.py

@@ -16,7 +16,7 @@ from meshtrade.common import BaseGRPCClient
 from meshtrade.iam.api_user.v1.api_credentials import find_credentials
 
 from .limit_order_pb2 import LimitOrder
-from .service_options_meshpy import ServiceOptions
+from meshtrade.common.service_options import ServiceOptions
 from .service_pb2 import (
 GetLimitOrderRequest,
 )

meshtrade/trading/market_order/v1/__init__.py

@@ -22,7 +22,6 @@ from .service_meshpy import (
     MarketOrderServiceGRPCClient,
     MarketOrderServiceGRPCClientInterface,
 )
-from .service_options_meshpy import ClientOptions
 
 # ===================================================================
 # END OF AUTO-GENERATED SECTION
@@ -44,7 +43,6 @@ from .service_options_meshpy import ClientOptions
 # Combined auto-generated and manual exports
 __all__ = [
     # Generated exports
-    "ClientOptions",
     "GetMarketOrderRequest",
     "MarketOrder",
     "MarketOrderService",

meshtrade/trading/market_order/v1/service_meshpy.py

@@ -16,7 +16,7 @@ from meshtrade.common import BaseGRPCClient
 from meshtrade.iam.api_user.v1.api_credentials import find_credentials
 
 from .market_order_pb2 import MarketOrder
-from .service_options_meshpy import ServiceOptions
+from meshtrade.common.service_options import ServiceOptions
 from .service_pb2 import (
 GetMarketOrderRequest,
 )

meshtrade/type/v1/amount.py

@@ -1,16 +1,21 @@
-"""
-This module provides a factory function for creating Amount protobuf messages.
+"""Amount utility functions for Mesh API.
+
+This module provides utility functions for working with Amount protobuf messages,
+including creation, validation, comparison, and arithmetic operations.
 """
 
-from decimal import ROUND_DOWN, Decimal
+from decimal import ROUND_DOWN
+from decimal import Decimal as PyDecimal
 
 from .amount_pb2 import Amount
 from .decimal_built_in_conversions import built_in_to_decimal, decimal_to_built_in
+from .decimal_pb2 import Decimal
 from .ledger import get_ledger_no_decimal_places
+from .token import new_undefined_token
 from .token_pb2 import Token
 
 
-def new_amount(value: Decimal, token: Token, precision_loss_tolerance: Decimal = Decimal("0.00000001")) -> Amount:
+def new_amount(value: PyDecimal, token: Token, precision_loss_tolerance: PyDecimal = PyDecimal("0.00000001")) -> Amount:
     """Creates a new Amount, ensuring the value conforms to system-wide limits.
 
     This function is the safe constructor for creating Amount protobuf messages.
@@ -67,7 +72,7 @@ def new_amount(value: Decimal, token: Token, precision_loss_tolerance: Decimal =
     # Truncate the validated value to the number of decimal places specified by the
     # token's ledger. ROUND_DOWN ensures the value is never inflated.
     truncated_value = value_after_roundtrip.quantize(
-        Decimal(10) ** -get_ledger_no_decimal_places(token.ledger),
+        PyDecimal(10) ** -get_ledger_no_decimal_places(token.ledger),
         rounding=ROUND_DOWN,
     )
 
@@ -76,3 +81,422 @@ def new_amount(value: Decimal, token: Token, precision_loss_tolerance: Decimal =
         token=token,
         value=built_in_to_decimal(truncated_value),
     )
+
+
+def new_undefined_amount(value: PyDecimal) -> Amount:
+    """Create a new Amount with the specified value and an undefined token.
+
+    This is useful as a placeholder or when the token type is not yet known.
+    Since undefined tokens don't have a valid ledger, this bypasses ledger
+    validation and creates the amount directly with full precision.
+
+    Args:
+        value: The decimal value for the amount
+
+    Returns:
+        A new Amount with the specified value and an undefined token
+
+    Example:
+        >>> from decimal import Decimal as PyDecimal
+        >>> amount = new_undefined_amount(PyDecimal("100"))
+        >>> amount_is_undefined(amount)
+        True
+    """
+    # Undefined tokens don't have a valid ledger, so we create the Amount directly
+    # without going through new_amount() which requires ledger validation
+    return Amount(
+        value=built_in_to_decimal(value),
+        token=new_undefined_token(),
+    )
+
+
+def amount_set_value(
+    amount: Amount,
+    value: PyDecimal,
+    precision_loss_tolerance: PyDecimal = PyDecimal("0.00000001"),
+) -> Amount:
+    """Create a new Amount with the given value and the same token as the input amount.
+
+    Despite its name, this function does NOT modify the input - it creates and returns a NEW Amount.
+
+    Args:
+        amount: The amount whose token to use
+        value: The decimal value for the new amount
+        precision_loss_tolerance: The maximum acceptable difference after validation
+            round-trip. Defaults to a small tolerance for robustness.
+
+    Returns:
+        A new Amount with the specified value and the same token
+
+    Raises:
+        ValueError: If amount is None
+        AssertionError: If the value exceeds system precision limits
+
+    Example:
+        >>> from decimal import Decimal as PyDecimal
+        >>> original = new_undefined_amount(PyDecimal("100"))
+        >>> modified = amount_set_value(original, PyDecimal("200"))
+        >>> # original is unchanged, modified is a new Amount with value 200
+    """
+    if amount is None:
+        raise ValueError("amount cannot be None")
+
+    # Check if the token is undefined (doesn't have a valid ledger)
+    from .token import token_is_undefined
+
+    if token_is_undefined(amount.token):
+        # For undefined tokens, create Amount directly without ledger validation
+        return Amount(
+            value=built_in_to_decimal(value),
+            token=amount.token,
+        )
+
+    return new_amount(value, amount.token, precision_loss_tolerance)
+
+
+def amount_is_undefined(amount: Amount | None) -> bool:
+    """Check whether this amount has an undefined token.
+
+    An amount is considered undefined if its associated token is undefined.
+
+    Args:
+        amount: Amount to check (can be None)
+
+    Returns:
+        True if the amount's token is undefined or if amount is None, False otherwise
+
+    None Safety:
+        Returns True if amount is None
+
+    Example:
+        >>> amount = new_undefined_amount(PyDecimal("100"))
+        >>> amount_is_undefined(amount)
+        True
+    """
+    if amount is None:
+        return True
+
+    from .token import token_is_undefined
+
+    return token_is_undefined(amount.token)
+
+
+def amount_is_same_type_as(amount1: Amount | None, amount2: Amount | None) -> bool:
+    """Check if two amounts have the same token type (same currency/asset).
+
+    This is useful for validating that amounts can be compared or combined arithmetically.
+
+    Args:
+        amount1: First amount (can be None)
+        amount2: Second amount (can be None)
+
+    Returns:
+        True if both amounts have equal tokens, False otherwise
+
+    None Safety:
+        Returns False if either amount is None
+
+    Example:
+        >>> usd_amount1 = new_undefined_amount(PyDecimal("100"))
+        >>> usd_amount2 = new_undefined_amount(PyDecimal("200"))
+        >>> amount_is_same_type_as(usd_amount1, usd_amount2)
+        True
+    """
+    if amount1 is None or amount2 is None:
+        return False
+
+    from .token import token_is_equal_to
+
+    return token_is_equal_to(amount1.token, amount2.token)
+
+
+def amount_is_equal_to(amount1: Amount | None, amount2: Amount | None) -> bool:
+    """Check if two amounts are equal in both value and token type.
+
+    Two amounts are considered equal if they have the same decimal value AND the same token.
+
+    Args:
+        amount1: First amount (can be None)
+        amount2: Second amount (can be None)
+
+    Returns:
+        True if both amounts have equal values and tokens (or both are None), False otherwise
+
+    None Safety:
+        Returns True if both are None, False if only one is None
+
+    Example:
+        >>> amount1 = new_undefined_amount(PyDecimal("100"))
+        >>> amount2 = new_undefined_amount(PyDecimal("100"))
+        >>> amount_is_equal_to(amount1, amount2)
+        True
+    """
+    if amount1 is None and amount2 is None:
+        return True
+    if amount1 is None or amount2 is None:
+        return False
+
+    from .decimal_operations import decimal_equal
+    from .token import token_is_equal_to
+
+    return token_is_equal_to(amount1.token, amount2.token) and decimal_equal(amount1.value, amount2.value)
+
+
+def amount_is_negative(amount: Amount | None) -> bool:
+    """Check whether the amount's value is less than zero.
+
+    Args:
+        amount: Amount to check (can be None)
+
+    Returns:
+        True if the value is negative (< 0), False otherwise
+
+    None Safety:
+        Returns False if amount is None
+
+    Example:
+        >>> amount = new_undefined_amount(PyDecimal("-50"))
+        >>> amount_is_negative(amount)
+        True
+    """
+    if amount is None:
+        return False
+
+    from .decimal_operations import decimal_is_negative
+
+    return decimal_is_negative(amount.value)
+
+
+def amount_is_zero(amount: Amount | None) -> bool:
+    """Check whether the amount's value is exactly zero.
+
+    Args:
+        amount: Amount to check (can be None)
+
+    Returns:
+        True if the value is zero, False otherwise
+
+    None Safety:
+        Returns False if amount is None
+
+    Example:
+        >>> amount = new_undefined_amount(PyDecimal("0"))
+        >>> amount_is_zero(amount)
+        True
+    """
+    if amount is None:
+        return False
+
+    from .decimal_operations import decimal_is_zero
+
+    return decimal_is_zero(amount.value)
+
+
+def amount_contains_fractions(amount: Amount | None) -> bool:
+    """Check whether the amount's value has any fractional (decimal) component.
+
+    This is useful for determining if an amount can be represented as a whole number.
+
+    Args:
+        amount: Amount to check (can be None)
+
+    Returns:
+        True if the value has fractional/decimal places, False otherwise
+
+    None Safety:
+        Returns False if amount is None
+
+    Example:
+        >>> amount1 = new_undefined_amount(PyDecimal("100.50"))
+        >>> amount_contains_fractions(amount1)
+        True
+        >>> amount2 = new_undefined_amount(PyDecimal("100"))
+        >>> amount_contains_fractions(amount2)
+        False
+    """
+    if amount is None:
+        return False
+
+    # Convert protobuf Decimal to Python Decimal
+    value = PyDecimal(amount.value.value) if amount.value and amount.value.value else PyDecimal(0)
+
+    # Check if truncating to 0 decimal places changes the value
+    return value.quantize(PyDecimal("1"), rounding=ROUND_DOWN) != value
+
+
+def amount_add(
+    amount1: Amount,
+    amount2: Amount,
+    precision_loss_tolerance: PyDecimal = PyDecimal("0.00000001"),
+) -> Amount:
+    """Add two amounts and return a new amount with the result.
+
+    The amounts must have the same token type (currency/asset).
+
+    Args:
+        amount1: First amount
+        amount2: Second amount (must have same token as amount1)
+        precision_loss_tolerance: The maximum acceptable difference after validation
+            round-trip. Defaults to a small tolerance for robustness.
+
+    Returns:
+        A new Amount containing the sum (amount1 + amount2)
+
+    Raises:
+        ValueError: If either amount is None or if the amounts have different token types
+        AssertionError: If the result exceeds system precision limits
+
+    Example:
+        >>> amount1 = new_undefined_amount(PyDecimal("100"))
+        >>> amount2 = new_undefined_amount(PyDecimal("30"))
+        >>> result = amount_add(amount1, amount2)
+        >>> # result value is 130
+    """
+    if amount1 is None:
+        raise ValueError("amount1 cannot be None")
+    if amount2 is None:
+        raise ValueError("amount2 cannot be None")
+
+    from .decimal_operations import decimal_add
+    from .token import token_is_equal_to, token_pretty_string
+
+    if not token_is_equal_to(amount1.token, amount2.token):
+        raise ValueError(
+            f"cannot do arithmetic on amounts of different token denominations: "
+            f"{token_pretty_string(amount1.token)} vs. {token_pretty_string(amount2.token)}"
+        )
+
+    new_value_decimal = decimal_add(amount1.value, amount2.value)
+    new_value_py = PyDecimal(new_value_decimal.value) if new_value_decimal.value else PyDecimal(0)
+
+    return amount_set_value(amount1, new_value_py, precision_loss_tolerance)
+
+
+def amount_sub(
+    amount1: Amount,
+    amount2: Amount,
+    precision_loss_tolerance: PyDecimal = PyDecimal("0.00000001"),
+) -> Amount:
+    """Subtract amount2 from amount1 and return a new amount with the result.
+
+    The amounts must have the same token type (currency/asset).
+
+    Args:
+        amount1: First amount
+        amount2: Second amount to subtract (must have same token as amount1)
+        precision_loss_tolerance: The maximum acceptable difference after validation
+            round-trip. Defaults to a small tolerance for robustness.
+
+    Returns:
+        A new Amount containing the difference (amount1 - amount2)
+
+    Raises:
+        ValueError: If either amount is None or if the amounts have different token types
+        AssertionError: If the result exceeds system precision limits
+
+    Example:
+        >>> amount1 = new_undefined_amount(PyDecimal("100"))
+        >>> amount2 = new_undefined_amount(PyDecimal("30"))
+        >>> result = amount_sub(amount1, amount2)
+        >>> # result value is 70
+    """
+    if amount1 is None:
+        raise ValueError("amount1 cannot be None")
+    if amount2 is None:
+        raise ValueError("amount2 cannot be None")
+
+    from .decimal_operations import decimal_sub
+    from .token import token_is_equal_to, token_pretty_string
+
+    if not token_is_equal_to(amount1.token, amount2.token):
+        raise ValueError(
+            f"cannot do arithmetic on amounts of different token denominations: "
+            f"{token_pretty_string(amount1.token)} vs. {token_pretty_string(amount2.token)}"
+        )
+
+    new_value_decimal = decimal_sub(amount1.value, amount2.value)
+    new_value_py = PyDecimal(new_value_decimal.value) if new_value_decimal.value else PyDecimal(0)
+
+    return amount_set_value(amount1, new_value_py, precision_loss_tolerance)
+
+
+def amount_decimal_mul(
+    amount: Amount,
+    multiplier: PyDecimal,
+    precision_loss_tolerance: PyDecimal = PyDecimal("0.00000001"),
+) -> Amount:
+    """Multiply this amount by a decimal value and return a new amount with the result.
+
+    The token type is preserved.
+
+    Args:
+        amount: The amount to multiply
+        multiplier: The decimal multiplier
+        precision_loss_tolerance: The maximum acceptable difference after validation
+            round-trip. Defaults to a small tolerance for robustness.
+
+    Returns:
+        A new Amount containing the product (amount * multiplier)
+
+    Raises:
+        ValueError: If amount is None
+        AssertionError: If the result exceeds system precision limits
+
+    Example:
+        >>> amount = new_undefined_amount(PyDecimal("100"))
+        >>> result = amount_decimal_mul(amount, PyDecimal("2"))
+        >>> # result value is 200
+    """
+    if amount is None:
+        raise ValueError("amount cannot be None")
+
+    from .decimal_operations import decimal_mul
+
+    multiplier_decimal = Decimal(value=str(multiplier))
+    new_value_decimal = decimal_mul(amount.value, multiplier_decimal)
+    new_value_py = PyDecimal(new_value_decimal.value) if new_value_decimal.value else PyDecimal(0)
+
+    return amount_set_value(amount, new_value_py, precision_loss_tolerance)
+
+
+def amount_decimal_div(
+    amount: Amount,
+    divisor: PyDecimal,
+    precision_loss_tolerance: PyDecimal = PyDecimal("0.00000001"),
+) -> Amount:
+    """Divide this amount by a decimal value and return a new amount with the result.
+
+    The token type is preserved.
+
+    Args:
+        amount: The amount to divide
+        divisor: The decimal divisor (must not be zero)
+        precision_loss_tolerance: The maximum acceptable difference after validation
+            round-trip. Defaults to a small tolerance for robustness.
+
+    Returns:
+        A new Amount containing the quotient (amount / divisor)
+
+    Raises:
+        ValueError: If amount is None
+        ZeroDivisionError: If divisor is zero
+        AssertionError: If the result exceeds system precision limits
+
+    Example:
+        >>> amount = new_undefined_amount(PyDecimal("100"))
+        >>> result = amount_decimal_div(amount, PyDecimal("4"))
+        >>> # result value is 25
+    """
+    if amount is None:
+        raise ValueError("amount cannot be None")
+
+    if divisor == 0:
+        raise ZeroDivisionError("cannot divide amount by zero")
+
+    from .decimal_operations import decimal_div
+
+    divisor_decimal = Decimal(value=str(divisor))
+    new_value_decimal = decimal_div(amount.value, divisor_decimal)
+    new_value_py = PyDecimal(new_value_decimal.value) if new_value_decimal.value else PyDecimal(0)
+
+    return amount_set_value(amount, new_value_py, precision_loss_tolerance)