hive-nectar 0.0.11__py3-none-any.whl → 0.1.1__py3-none-any.whl

nectar/hive.py

@@ -4,7 +4,7 @@ import math
 from datetime import date, datetime, timezone
 
 from nectar.blockchaininstance import BlockChainInstance
-from nectar.constants import STEEM_100_PERCENT
+from nectar.constants import HIVE_100_PERCENT
 from nectargraphenebase.chains import known_chains
 
 from .amount import Amount
@@ -59,7 +59,7 @@ class Hive(BlockChainInstance):
     * **Providing Keys**: Here, you can provide the keys for
       your accounts manually. All you need to do is add the wif
       keys for the accounts you want to use as a simple array
-      using the ``keys`` parameter to ``Steem()``.
+      using the ``keys`` parameter to ``Hive()``.
     * **Force keys**: This more is for advanced users and
       requires that you know what you are doing. Here, the
       ``keys`` parameter is a dictionary that overwrite the
@@ -94,9 +94,9 @@ class Hive(BlockChainInstance):
     .. code-block:: python
 
         from nectar import Hive
-        stm = Hive(node=["https://mytstnet.com"], custom_chains={"MYTESTNET":
+        hv = Hive(node=["https://mytstnet.com"], custom_chains={"MYTESTNET":
             {'chain_assets': [{'asset': 'HBD', 'id': 0, 'precision': 3, 'symbol': 'HBD'},
-                              {'asset': 'STEEM', 'id': 1, 'precision': 3, 'symbol': 'STEEM'},
+                              {'asset': 'HIVE', 'id': 1, 'precision': 3, 'symbol': 'HIVE'},
                               {'asset': 'VESTS', 'id': 2, 'precision': 6, 'symbol': 'VESTS'}],
              'chain_id': '79276aea5d4877d9a25892eaa01b0adf019d3e5cb12a97478df3298ccdd01674',
              'min_version': '0.0.0',
@@ -220,11 +220,25 @@ class Hive(BlockChainInstance):
         self,
         token_power,
         post_rshares=0,
-        voting_power=STEEM_100_PERCENT,
-        vote_pct=STEEM_100_PERCENT,
+        voting_power=HIVE_100_PERCENT,
+        vote_pct=HIVE_100_PERCENT,
         not_broadcasted_vote=True,
         use_stored_data=True,
     ):
+        """
+        Convert token power (Hive Power) to its token-backed dollar equivalent (HBD).
+
+        Parameters:
+            token_power: Hive Power amount (numeric or Amount-like) to convert.
+            post_rshares (int): Optional existing rshares on the post to include when estimating payout.
+            voting_power (int): Voter's current voting power (use HIVE_100_PERCENT for full power).
+            vote_pct (int): Vote weight to apply (use HIVE_100_PERCENT for 100%).
+            not_broadcasted_vote (bool): If True, include the vote as not-yet-broadcasted when computing reward pool effects.
+            use_stored_data (bool): If True, prefer cached chain data when available.
+
+        Returns:
+            The estimated HBD value (token-backed dollar) corresponding to the provided token power.
+        """
         return self.hp_to_hbd(
             token_power,
             post_rshares=post_rshares,
@@ -238,21 +252,24 @@ class Hive(BlockChainInstance):
         self,
         hp,
         post_rshares=0,
-        voting_power=STEEM_100_PERCENT,
-        vote_pct=STEEM_100_PERCENT,
+        voting_power=HIVE_100_PERCENT,
+        vote_pct=HIVE_100_PERCENT,
         not_broadcasted_vote=True,
         use_stored_data=True,
     ):
-        """Obtain the resulting HBD vote value from Hive power
-
-        :param number hive_power: Hive Power
-        :param int post_rshares: rshares of post which is voted
-        :param int voting_power: voting power (100% = 10000)
-        :param int vote_pct: voting percentage (100% = 10000)
-        :param bool not_broadcasted_vote: not_broadcasted or already broadcasted vote (True = not_broadcasted vote).
-
-        Only impactful for very big votes. Slight modification to the value calculation, as the not_broadcasted
-        vote rshares decreases the reward pool.
+        """
+        Convert Hive Power (HP) to the estimated HBD payout this vote would produce.
+
+        Parameters:
+            hp (number): Amount of Hive Power to convert.
+            post_rshares (int): Current post rshares to include when computing marginal effect of this vote.
+            voting_power (int): Voter's current voting power (100% = 10000).
+            vote_pct (int): Vote percentage to apply (100% = 10000).
+            not_broadcasted_vote (bool): If True, treat the vote as not yet broadcast — the function will account for the vote reducing the available reward pool when applicable.
+            use_stored_data (bool): If True, use cached chain/state data when available.
+
+        Returns:
+            HBD value corresponding to the provided HP under the current reward pool and price conditions (same type/format as the library's Amount/HBD results).
         """
         vesting_shares = int(self.hp_to_vests(hp, use_stored_data=use_stored_data))
         return self.vests_to_hbd(
@@ -268,21 +285,28 @@ class Hive(BlockChainInstance):
         self,
         vests,
         post_rshares=0,
-        voting_power=STEEM_100_PERCENT,
-        vote_pct=STEEM_100_PERCENT,
+        voting_power=HIVE_100_PERCENT,
+        vote_pct=HIVE_100_PERCENT,
         not_broadcasted_vote=True,
         use_stored_data=True,
     ):
-        """Obtain the resulting HBD vote value from vests
-
-        :param number vests: vesting shares
-        :param int post_rshares: rshares of post which is voted
-        :param int voting_power: voting power (100% = 10000)
-        :param int vote_pct: voting percentage (100% = 10000)
-        :param bool not_broadcasted_vote: not_broadcasted or already broadcasted vote (True = not_broadcasted vote).
-
-        Only impactful for very big votes. Slight modification to the value calculation, as the not_broadcasted
-        vote rshares decreases the reward pool.
+        """
+        Convert vesting shares to their equivalent HBD payout for a single vote.
+
+        Given vesting shares, computes the vote's r-shares (taking into account post r-shares,
+        voter power and percentage) and converts that r-shares value to an HBD payout.
+
+        Parameters:
+            vests: Vesting shares to use for the vote (number or Amount-like).
+            post_rshares (int): Existing r-shares of the post being voted on; affects the r-shares calculation.
+            voting_power (int): Voter's current voting power (units where 100% == HIVE_100_PERCENT).
+            vote_pct (int): Vote percentage to apply (units where 100% == HIVE_100_PERCENT).
+            not_broadcasted_vote (bool): If True, treat this as a not-yet-broadcast vote (it reduces the effective reward pool);
+                if False, treat as already-applied (affects conversion math for very large votes).
+            use_stored_data (bool): Whether to use cached chain parameters/reward state or query fresh data.
+
+        Returns:
+            The estimated HBD value (same type returned by rshares_to_hbd) for the vote.
         """
         vote_rshares = self.vests_to_rshares(
             vests, post_rshares=post_rshares, voting_power=voting_power, vote_pct=vote_pct
@@ -295,17 +319,24 @@ class Hive(BlockChainInstance):
         self,
         hive_power,
         post_rshares=0,
-        voting_power=STEEM_100_PERCENT,
-        vote_pct=STEEM_100_PERCENT,
+        voting_power=HIVE_100_PERCENT,
+        vote_pct=HIVE_100_PERCENT,
         use_stored_data=True,
     ):
-        """Obtain the r-shares from Hive power
+        """
+        Convert Hive Power (HP) to r-shares used for voting.
+
+        Given a Hive Power amount, computes the equivalent vesting shares and then the r-shares that a vote with the specified voting_power and vote_pct would produce against a post that currently has post_rshares. `voting_power` and `vote_pct` use the chain-normalized scale (100% == HIVE_100_PERCENT).
 
-        :param number hive_power: Hive Power
-        :param int post_rshares: rshares of post which is voted
-        :param int voting_power: voting power (100% = 10000)
-        :param int vote_pct: voting percentage (100% = 10000)
+        Parameters:
+            hive_power (number): Hive Power (HP) value to convert.
+            post_rshares (int, optional): Current r-shares of the post being voted on; used to adjust the resulting r-shares. Defaults to 0.
+            voting_power (int, optional): Voter's current voting power on the HIVE_100_PERCENT scale. Defaults to HIVE_100_PERCENT.
+            vote_pct (int, optional): Vote percentage to apply on the HIVE_100_PERCENT scale. Defaults to HIVE_100_PERCENT.
+            use_stored_data (bool, optional): Whether to use cached chain data when performing conversions. Defaults to True.
 
+        Returns:
+            int: The computed r-shares produced by the specified vote.
         """
         # calculate our account voting shares (from vests)
         vesting_shares = int(self.hp_to_vests(hive_power, use_stored_data=use_stored_data))
@@ -322,24 +353,36 @@ class Hive(BlockChainInstance):
         self,
         vests,
         post_rshares=0,
-        voting_power=STEEM_100_PERCENT,
-        vote_pct=STEEM_100_PERCENT,
+        voting_power=HIVE_100_PERCENT,
+        vote_pct=HIVE_100_PERCENT,
         subtract_dust_threshold=True,
         use_stored_data=True,
     ):
-        """Obtain the r-shares from vests
-
-        :param number vests: vesting shares
-        :param int post_rshares: rshares of post which is voted
-        :param int voting_power: voting power (100% = 10000)
-        :param int vote_pct: voting percentage (100% = 10000)
-
+        """
+        Convert vesting shares to vote r-shares.
+
+        Detailed behavior:
+        - `vests` is the voter's vesting amount in VESTS (not in micro-vests); the implementation multiplies this value by 1e6 internally.
+        - Computes the effective voting power using `voting_power` and `vote_pct`, applies Hive's normalization (HIVE_100_PERCENT), and returns the signed r-shares for that vote.
+        - If `subtract_dust_threshold` is True, results at or below the chain dust threshold return 0; otherwise the threshold is subtracted from the computed r-shares.
+        - The final r-shares are adjusted by `post_rshares` using the chain's vote-claim logic before being returned.
+
+        Parameters:
+            vests (int|float|Amount): Vesting shares in VESTS.
+            post_rshares (int): Current r-shares on the post being voted (used to compute claim adjustment).
+            voting_power (int): Voter's current voting power (100% == HIVE_100_PERCENT).
+            vote_pct (int): Vote percentage to apply (100% == HIVE_100_PERCENT); sign of this value determines vote direction.
+            subtract_dust_threshold (bool): If True, apply/subtract the chain dust threshold from the computed r-shares.
+            use_stored_data (bool): Whether to use cached chain data for thresholds and calculations.
+
+        Returns:
+            int: Signed r-shares resulting from the provided vesting shares and vote parameters.
         """
         used_power = self._calc_resulting_vote(
             voting_power=voting_power, vote_pct=vote_pct, use_stored_data=use_stored_data
         )
         # calculate vote rshares
-        rshares = int(math.copysign(vests * 1e6 * used_power / STEEM_100_PERCENT, vote_pct))
+        rshares = int(math.copysign(vests * 1e6 * used_power / HIVE_100_PERCENT, vote_pct))
         if subtract_dust_threshold:
             if abs(rshares) <= self.get_dust_threshold(use_stored_data=use_stored_data):
                 return 0
@@ -404,22 +447,36 @@ class Hive(BlockChainInstance):
         post_rshares=0,
         hive_power=None,
         vests=None,
-        voting_power=STEEM_100_PERCENT,
+        voting_power=HIVE_100_PERCENT,
         use_stored_data=True,
     ):
-        """Obtain the voting percentage for a desired rshares value
-        for a given Hive Power or vesting shares and voting_power
-        Give either hive_power or vests, not both.
-        When the output is greater than 10000 or less than -10000,
-        the given absolute rshares are too high
-
-        Returns the required voting percentage (100% = 10000)
-
-        :param number rshares: desired rshares value
-        :param number hive_power: Hive Power
-        :param number vests: vesting shares
-        :param int voting_power: voting power (100% = 10000)
-
+        """
+        Compute the voting percentage required to achieve a target r-shares value.
+
+        Given a desired r-shares (positive for upvotes, negative for downvotes) and either
+        hive_power or vests (exactly one must be provided), return the voting percentage
+        where 100% = 10000. The calculation accounts for post-vote r-shares adjustments,
+        current dust-threshold behavior (post-hardfork), and the configured voting power.
+
+        Parameters:
+            rshares (int | float): Target r-shares value (signed).
+            post_rshares (int, optional): R-shares already present on the post (positive
+                for existing upvotes, negative for downvotes). Defaults to 0.
+            hive_power (float, optional): Hive Power to use for the calculation. Provide
+                this or `vests`, not both. If given, it is converted to vesting shares.
+            vests (int, optional): Vesting shares (in micro-vests, i.e., vest*1e6). Provide
+                this or `hive_power`, not both.
+            voting_power (int, optional): Voter's current voting power where 100% = 10000.
+                Defaults to HIVE_100_PERCENT.
+            use_stored_data (bool, optional): Whether to use cached chain properties when
+                available. Defaults to True.
+
+        Returns:
+            int: Signed voting percentage required (100% = 10000). The sign matches the
+            sign of `rshares`.
+
+        Raises:
+            ValueError: If neither or both of `hive_power` and `vests` are provided.
         """
         if hive_power is None and vests is None:
             raise ValueError("Either hive_power or vests has to be set!")
@@ -450,10 +507,10 @@ class Hive(BlockChainInstance):
 
         max_vote_denom = self._max_vote_denom(use_stored_data=use_stored_data)
 
-        used_power = int(math.ceil(abs(rshares) * STEEM_100_PERCENT / vests))
+        used_power = int(math.ceil(abs(rshares) * HIVE_100_PERCENT / vests))
         used_power = used_power * max_vote_denom
 
-        vote_pct = used_power * STEEM_100_PERCENT / (60 * 60 * 24) / voting_power
+        vote_pct = used_power * HIVE_100_PERCENT / (60 * 60 * 24) / voting_power
         return int(math.copysign(vote_pct, rshares))
 
     def hbd_to_vote_pct(
@@ -462,26 +519,29 @@ class Hive(BlockChainInstance):
         post_rshares=0,
         hive_power=None,
         vests=None,
-        voting_power=STEEM_100_PERCENT,
+        voting_power=HIVE_100_PERCENT,
         not_broadcasted_vote=True,
         use_stored_data=True,
     ):
-        """Obtain the voting percentage for a desired HBD value
-        for a given Hive Power or vesting shares and voting power
-        Give either Hive Power or vests, not both.
-        When the output is greater than 10000 or smaller than -10000,
-        the HBD value is too high.
+        """
+        Calculate the voting percentage required to achieve a target HBD payout for a given voting power and stake.
 
-        Returns the required voting percentage (100% = 10000)
+        Given a desired HBD amount, this returns the vote percentage (100% == 10000) that, when applied from the provided Hive Power or vesting shares, would produce approximately that payout. Exactly one of `hive_power` or `vests` must be provided.
 
-        :param hbd: desired HBD value
-        :type hbd: str, int, amount.Amount
-        :param number hive_power: Hive Power
-        :param number vests: vesting shares
-        :param bool not_broadcasted_vote: not_broadcasted or already broadcasted vote (True = not_broadcasted vote).
-         Only impactful for very high amounts of HBD. Slight modification to the value calculation, as the not_broadcasted
-         vote rshares decreases the reward pool.
+        Parameters:
+            hbd (str|int|Amount): Desired HBD payout. Accepts an Amount, numeric value, or asset string; will be converted to an Amount in the chain's HBD symbol.
+            hive_power (number, optional): Voter's Hive Power. Mutually exclusive with `vests`.
+            vests (number, optional): Voter's vesting shares. Mutually exclusive with `hive_power`.
+            voting_power (int, optional): Current voting power normalization constant (default HIVE_100_PERCENT).
+            not_broadcasted_vote (bool, optional): If True, treat the vote as not yet broadcast; this slightly changes calculations for very large HBD amounts because an unbroadcasted vote reduces the available reward pool.
+            post_rshares (int, optional): rshares already present on the post (used when calculating required vote to reach a target).
+            use_stored_data (bool, optional): Use cached chain properties when available.
+
+        Returns:
+            int: Required vote percentage where 100% == 10000. Values >10000 or < -10000 indicate the requested HBD is too large for a single vote.
 
+        Raises:
+            AssertionError: If the provided `hbd` cannot be interpreted as the chain's HBD asset.
         """
         if isinstance(hbd, Amount):
             hbd = Amount(hbd, blockchain_instance=self)

nectar/hivesigner.py

@@ -2,7 +2,7 @@
 import json
 
 try:
-    from urllib.parse import urlencode, urljoin, urlparse
+    from urllib.parse import urlencode, urljoin
 except ImportError:
     from urllib import urlencode
 
@@ -29,27 +29,27 @@ class HiveSigner(object):
 
     .. code-block:: python
 
-        # Run the login_app in examples and login with a account
-        from nectar import Steem
-        from nectar.HiveSigner import HiveSigner
+        # Run the login_app in examples and login with an account
+        from nectar import Hive
+        from nectar.hivesigner import HiveSigner
         from nectar.comment import Comment
         hs = HiveSigner(client_id="nectarflower")
-        steem = Steem(HiveSigner=hs)
-        steem.wallet.unlock("supersecret-passphrase")
-        post = Comment("author/permlink", blockchain_instance=steem)
+        hive = Hive(HiveSigner=hs)
+        hive.wallet.unlock("supersecret-passphrase")
+        post = Comment("author/permlink", blockchain_instance=hive)
         post.upvote(voter="test")  # replace "test" with your account
 
     Examples for creating HiveSigner urls for broadcasting in browser:
 
     .. testoutput::
 
-        from nectar import Steem
+        from nectar import Hive
         from nectar.account import Account
-        from nectar.HiveSigner import HiveSigner
+        from nectar.hivesigner import HiveSigner
         from pprint import pprint
-        steem = Steem(nobroadcast=True, unsigned=True)
-        hs = HiveSigner(blockchain_instance=steem)
-        acc = Account("test", blockchain_instance=steem)
+        hive = Hive(nobroadcast=True, unsigned=True)
+        hs = HiveSigner(blockchain_instance=hive)
+        acc = Account("test", blockchain_instance=hive)
         pprint(hs.url_from_tx(acc.transfer("test1", 1, "HIVE", "test")))
 
     .. testcode::
@@ -58,14 +58,14 @@ class HiveSigner(object):
 
     .. testoutput::
 
-        from nectar import Steem
+        from nectar import Hive
         from nectar.transactionbuilder import TransactionBuilder
         from nectarbase import operations
-        from nectar.HiveSigner import HiveSigner
+        from nectar.hivesigner import HiveSigner
         from pprint import pprint
-        stm = Steem(nobroadcast=True, unsigned=True)
-        hs = HiveSigner(blockchain_instance=stm)
-        tx = TransactionBuilder(blockchain_instance=stm)
+        hive = Hive(nobroadcast=True, unsigned=True)
+        hs = HiveSigner(blockchain_instance=hive)
+        tx = TransactionBuilder(blockchain_instance=hive)
         op = operations.Transfer(**{"from": 'test',
                                     "to": 'test1',
                                     "amount": '1.000 HIVE',
@@ -80,11 +80,20 @@ class HiveSigner(object):
     """
 
     def __init__(self, blockchain_instance=None, *args, **kwargs):
-        if blockchain_instance is None:
-            if kwargs.get("steem_instance"):
-                blockchain_instance = kwargs["steem_instance"]
-            elif kwargs.get("hive_instance"):
-                blockchain_instance = kwargs["hive_instance"]
+        """
+        Initialize HiveSigner integration.
+
+        Sets up the blockchain client (uses provided instance or the shared global), OAuth/client configuration, and the token store.
+
+        Detailed behavior:
+        - Resolves self.blockchain from blockchain_instance or shared_blockchain_instance().
+        - Reads defaults from blockchain config for client_id, scope, OAuth base URL, API URL, and hot-sign redirect URI.
+        - Normalizes hot_sign_redirect_uri to None if an empty string is provided.
+        - Stores get_refresh_token, client_id, scope, hs_oauth_base_url, and hs_api_url on the instance.
+        - Token handling:
+          - If a non-empty "token" is provided in kwargs, an in-memory token store is created, the access token is set, the associated username is fetched via me(), and the token is stored under that username.
+          - Otherwise a persistent token store is used: either the token_store passed in kwargs or a SqliteEncryptedTokenStore initialized with the blockchain config and kwargs.
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
         self.access_token = None
         config = self.blockchain.config
@@ -120,11 +129,25 @@ class HiveSigner(object):
 
     @property
     def headers(self):
+        """
+        Return the HTTP Authorization headers for the current access token.
+
+        Returns:
+            dict: A headers dictionary with the "Authorization" key set to the current access token (may be None if no token is set).
+        """
         return {"Authorization": self.access_token}
 
     def setToken(self, loadtoken):
-        """This method is strictly only for in memory token that are
-        passed to Wallet/Steem with the ``token`` argument
+        """
+        Force-add tokens into the token store from an in-memory mapping.
+
+        Accepts a mapping of public-name -> token and stores each entry into the configured token store. Intended for use when tokens are provided directly (e.g., via a `token` argument) and should be loaded into the in-memory store.
+
+        Parameters:
+            loadtoken (dict): Mapping where keys are public names and values are the corresponding private token strings.
+
+        Raises:
+            ValueError: If `loadtoken` is not a dict.
         """
         log.debug("Force setting of private token. Not using the wallet database!")
         if not isinstance(loadtoken, (dict)):
@@ -255,15 +278,16 @@ class HiveSigner(object):
         return r.json()
 
     def me(self, username=None):
-        """Calls the me function from HiveSigner
+        """
+        Retrieve the current user's information from HiveSigner.
 
-        .. code-block:: python
+        If a username is provided, sets the access token for that username (via set_username) before calling the HiveSigner "me" endpoint. Performs an authenticated POST to the HiveSigner me endpoint and returns the parsed JSON response.
 
-            from nectar.HiveSigner import HiveSigner
-            hs = HiveSigner()
-            hs.steem.wallet.unlock("supersecret-passphrase")
-            hs.me(username="test")
+        Parameters:
+            username (str, optional): Public account name whose token should be used for the request. If omitted, the currently configured access token is used.
 
+        Returns:
+            dict: Parsed JSON response from the HiveSigner me endpoint.
         """
         if username:
             self.set_username(username)
@@ -285,23 +309,17 @@ class HiveSigner(object):
         self.access_token = self.getTokenForAccountName(username)
 
     def broadcast(self, operations, username=None):
-        """Broadcast an operation
-
-        Sample operations:
+        """
+        Broadcast a list of Hive operations via the HiveSigner API.
 
-        .. code-block:: js
+        Sends a POST request to the HiveSigner broadcast endpoint with the provided operations. If `username` is given, the method will set the access token for that user before sending the request.
 
-            [
-                [
-                    'vote', {
-                                'voter': 'gandalf',
-                                'author': 'gtg',
-                                'permlink': 'steem-pressure-4-need-for-speed',
-                                'weight': 10000
-                            }
-                ]
-            ]
+        Parameters:
+            operations (list): A list of operations in the form [[operation_name, operation_payload], ...].
+            username (str, optional): Public account name whose stored token should be used for authorization.
 
+        Returns:
+            dict or bytes: The parsed JSON response from the API, or raw response content if the body is not valid JSON.
         """
         url = urljoin(self.hs_api_url, "broadcast/")
         data = {
@@ -357,10 +375,19 @@ class HiveSigner(object):
         return r.json()
 
     def url_from_tx(self, tx, redirect_uri=None):
-        """Creates a link for broadcasting an operation
+        """
+        Generate HiveSigner hot-sign URLs for each operation in a transaction.
+
+        Given a transaction dict (or an object with a .json() method returning such a dict), produce a HiveSigner "hot sign" URL for each operation. If the transaction has no operations an empty string is returned. For each operation the function normalizes parameter values before building the URL:
+        - 3-element lists are treated as amounts and converted to the blockchain's Amount string when possible.
+        - booleans are converted to 1 (True) or 0 (False).
+        - other values are left as-is.
 
-        :param dict tx: includes the operation, which should be broadcast
-        :param str redirect_uri: Redirects to this uri, when set
+        Returns either a single URL string when the transaction contains one operation, a list of URL strings for multiple operations, or an empty string when there are no operations.
+
+        Parameters:
+            tx (dict | object): Transaction data or an object implementing .json() that returns a dict with an "operations" list.
+            redirect_uri (str, optional): If provided, included in each generated hot-sign URL as the post-sign redirect target.
         """
         if not isinstance(tx, dict):
             tx = tx.json()
@@ -390,31 +417,42 @@ class HiveSigner(object):
         else:
             return urls
 
-    def create_hot_sign_url(self, operation, params, redirect_uri=None):
-        """Creates a link for broadcasting an operation
+    def sign(self, tx):
+        """
+        Create a transaction shaped as if signed by HiveSigner.
+
+        This method does not perform real cryptographic signing locally; instead it validates
+        the transaction structure and returns a copy containing a mock signature entry so
+        callers that expect a "signed" transaction can proceed (actual signing is performed
+        server-side by HiveSigner during broadcasting).
+
+        Parameters:
+            tx (dict): Transaction object that must include a non-empty "operations" list.
+
+        Returns:
+            dict: A copy of `tx` with a "signatures" list containing a mock HiveSigner signature.
 
-        :param str operation: operation name (e.g.: vote)
-        :param dict params: operation dict params
-        :param str redirect_uri: Redirects to this uri, when set
+        Raises:
+            ValueError: If `tx` is not a dict or if it lacks a non-empty "operations" list.
         """
+        if not isinstance(tx, dict):
+            raise ValueError("Transaction must be a dictionary")
 
-        if not isinstance(operation, str) or not isinstance(params, dict):
-            raise ValueError("Invalid Request.")
+        if "operations" not in tx or not tx["operations"]:
+            raise ValueError("Transaction must contain operations")
 
-        base_url = self.hs_api_url.replace("https://api.", "https://").replace("/api", "")
-        if redirect_uri == "":
-            redirect_uri = None
+        # For HiveSigner, we don't actually sign locally - the signing happens
+        # server-side when broadcast() is called. However, we need to return
+        # a transaction that looks signed for compatibility.
 
-        if redirect_uri is None and self.hot_sign_redirect_uri is not None:
-            redirect_uri = self.hot_sign_redirect_uri
-        if redirect_uri is not None:
-            params.update({"redirect_uri": redirect_uri})
+        # Create a copy of the transaction
+        signed_tx = tx.copy()
 
-        for key in params:
-            if isinstance(params[key], list):
-                params[key] = json.dumps(params[key])
-        params = urlencode(params)
-        url = urljoin(base_url, "sign/%s" % operation)
-        url += "?" + params
+        # Add a mock signature to indicate this was processed by HiveSigner
+        # In a real implementation, this would be replaced with actual signatures
+        # from the HiveSigner API response
+        mock_signature = "hivesigner_signature_placeholder"
+        signed_tx["signatures"] = [mock_signature]
 
-        return url
+        log.debug(f"HiveSigner sign: processed transaction with {len(tx['operations'])} operations")
+        return signed_tx