Merge pull request #69 from icon-project/experimental/query_with_height

Add "height" key "params" of query request

Author: Eunsoo Park

README.md

@@ -122,6 +122,7 @@ call = CallBuilder().from_(wallet.get_address())\
                     .to("cx000...1")\
                     .method("balance_of")\
                     .params({"address": "hx000...1"})\
+                    .height(100)\
                     .build()
 
 # Executes a call method to call a read-only API method on the SCORE immediately without creating a transaction
@@ -185,7 +186,7 @@ block = icon_service.get_block("latest")
 ### get_balance
 
 ```python
-get_balance(address: str)
+get_balance(address: str, height: int = None)
 ```
 
 Returns the ICX balance of the given EOA or SCORE
@@ -196,6 +197,8 @@ Delegates to **icx_getBalance** RPC method
 
 address : An address of EOA or SCORE
 
+height(optional) : Block height
+
 #### Returns
 
 Number of ICX coins
@@ -218,7 +221,7 @@ balance = icon_service.get_balance("hx000...1")
 ### get_score_api
 
 ```python
-get_score_api(address: str)
+get_score_api(address: str, height: int = None)
 ```
 
 Returns SCORE's external API list
@@ -229,6 +232,8 @@ Delegates to **icx_getScoreApi** RPC method
 
 address : A SCORE address to be examined
 
+height(optional) : Block height
+
 #### Returns
 
 A list of API methods of the SCORE and its information
@@ -264,7 +269,7 @@ score_apis = icon_service.get_score_api("cx000...1")
 ### get_total_supply
 
 ```python
-get_total_supply()
+get_total_supply(height: int = None)
 ```
 
 Returns total ICX coin supply that has been issued
@@ -273,7 +278,7 @@ Delegates to **icx_getTotalSupply** RPC method
 
 #### Parameters
 
-None
+height(optional) : Block height
 
 #### Returns
 

iconsdk/builder/call_builder.py

@@ -22,11 +22,12 @@ class Call:
     Class `Call` for calling a SCORE API.
     Once an instance generated, it is read-only."""
 
-    def __init__(self, from_: str, to: str, method: str, params: dict):
+    def __init__(self, from_: str, to: str, method: str, params: dict, height: int):
         self.__from = from_
         self.__to = to
         self.__method = method
         self.__params = params
+        self.__height = height
 
     @property
     def from_(self) -> str:
@@ -44,8 +45,12 @@ def method(self) -> str:
     def params(self) -> dict:
         return object_to_str(self.__params) if self.__params else None
 
+    @property
+    def height(self) -> int:
+        return object_to_str(self.__height) if self.__height else None
+
     def to_dict(self) -> dict:
-        return {"from_": self.from_, "to": self.to, "method": self.method, "params": self.params}
+        return {"from_": self.from_, "to": self.to, "method": self.method, "params": self.params, "height": self.height}
 
 
 class CallBuilder:
@@ -54,11 +59,13 @@ class CallBuilder:
     Once setting it, a value of any property can't be changed forever.
     """
 
-    def __init__(self, from_: str = None, to: str = None, method: str = None, params: dict = None) -> Call:
+    def __init__(self, from_: str = None, to: str = None, method: str = None, params: dict = None,
+                 height: int = None) -> Call:
         self._from_ = from_
         self._to = to
         self._method = method
         self._params = params
+        self._height = height
 
     def from_(self, from_: str) -> 'CallBuilder':
         self._from_ = from_
@@ -76,8 +83,12 @@ def params(self, params: dict) -> 'CallBuilder':
         self._params = params
         return self
 
+    def height(self, height: int) -> 'CallBuilder':
+        self._height = height
+        return self
+
     def build(self) -> Call:
-        return Call(self._from_, self._to, self._method, self._params)
+        return Call(self._from_, self._to, self._method, self._params, self._height)
 
     @classmethod
     def from_dict(cls, call_as_dict: dict) -> 'CallBuilder':
@@ -87,7 +98,8 @@ def from_dict(cls, call_as_dict: dict) -> 'CallBuilder':
                 from_=call_as_dict['from_'] if "from_" in call_as_dict else None,
                 to=call_as_dict['to'],
                 method=call_as_dict['method'],
-                params=call_as_dict['params'] if "params" in call_as_dict else None
+                params=call_as_dict['params'] if "params" in call_as_dict else None,
+                height=call_as_dict['height'],
             )
         except KeyError:
             raise DataTypeException("The input data invalid. Mapping key not found.")

iconsdk/icon_service.py

@@ -115,33 +115,41 @@ def return_infos_by_block_version(_prev_method: str) -> Tuple[str, Any, bool]:
 
         return result
 
-    def get_total_supply(self, full_response: bool = False) -> Union[dict, int]:
+    def get_total_supply(self, height: int = None, full_response: bool = False) -> Union[dict, int]:
         """
         Returns total ICX coin supply that has been issued
         Delegates to icx_getTotalSupply RPC method
 
+        :param height: Block height
         :param full_response: Boolean to check whether get naive dict or refined data from server
         :return: Total number of ICX coins issued
         """
 
-        result = self.__provider.make_request('icx_getTotalSupply', full_response=full_response)
+        params = {}
+        if height is not None:
+            params["height"] = hex(height)
+
+        result = self.__provider.make_request('icx_getTotalSupply', params, full_response=full_response)
 
         if full_response:
             return result
         else:
             return int(remove_0x_prefix(result), 16)
 
-    def get_balance(self, address: str, full_response: bool = False) -> Union[dict, int]:
+    def get_balance(self, address: str, height: int = None, full_response: bool = False) -> Union[dict, int]:
         """
         Returns the ICX balance of the given EOA or SCORE.
         Delegates to icx_getBalance RPC method.
 
         :param address: An address of EOA or SCORE. type(str)
+        :param height: Block height. type(int)
         :param full_response: Boolean to check whether get naive dict or refined data from server
         :return: Number of ICX coins
         """
         if is_score_address(address) or is_wallet_address(address):
             params = {'address': address}
+            if height is not None:
+                params["height"] = hex(height)
 
             result = self.__provider.make_request('icx_getBalance', params, full_response)
 
@@ -152,19 +160,22 @@ def get_balance(self, address: str, full_response: bool = False) -> Union[dict,
         else:
             raise AddressException("Address is wrong.")
 
-    def get_score_api(self, address: str, full_response: bool = False) -> Union[dict, list]:
+    def get_score_api(self, address: str, height: int = None, full_response: bool = False) -> Union[dict, list]:
         """
         Returns SCORE's external API list.
         Delegates to icx_getScoreApi RPC method.
 
         :param address: A SCORE address to be examined
+        :param height: Block height
         :param full_response: Boolean to check whether get naive dict or refined data from server
         :return: A list of API methods of the SCORE and its information
         """
         if not is_score_address(address):
             raise AddressException("SCORE Address is wrong.")
 
         params = {'address': address}
+        if height is not None:
+            params['height'] = hex(height)
         return self.__provider.make_request('icx_getScoreApi', params, full_response)
 
     def get_transaction_result(self, tx_hash: str, full_response: bool = False) -> dict:
@@ -255,6 +266,9 @@ def call(self, call: object, full_response: bool = False) -> Union[dict, str]:
         if isinstance(call.params, dict):
             params["data"]["params"] = call.params
 
+        if call.height is not None:
+            params["height"] = call.height
+
         return self.__provider.make_request('icx_call', params, full_response)
 
     def send_transaction(self, signed_transaction: SignedTransaction, full_response: bool = False) -> Union[dict, str]:

tests/api_get/test_get_balance.py

@@ -48,6 +48,11 @@ def test_get_balance_from_wallet(self, _make_id):
             self.assertEqual(expected_request, actual_request)
             self.assertEqual(expected_result, result)
 
+            # with height
+            self.icon_service.get_balance(self.setting['from'], height=self.setting['height'])
+            actual_request = json.loads(m._adapter.last_request.text)
+            self.assertEqual(hex(self.setting['height']), actual_request['params']['height'])
+
     def test_get_balance_invalid(self, _make_id):
         # case 1: when a param is wrong.
         self.assertRaises(AddressException, self.icon_service.get_balance, self.setting["to"][2:])

tests/api_get/test_get_score_api.py

@@ -46,6 +46,11 @@ def test_get_score_api(self, _make_id):
             self.assertTrue(result)
             self.assertTrue(is_score_apis(result))
 
+            # with height
+            self.icon_service.get_score_api(governance_address, height=self.setting['height'])
+            actual_request = json.loads(m._adapter.last_request.text)
+            self.assertEqual(hex(self.setting['height']), actual_request['params']['height'])
+
     def test_get_score_api_invalid(self, _make_id):
         # case 1: when address is wrong - wallet address
         self.assertRaises(AddressException, self.icon_service.get_score_api,

tests/api_get/test_get_total_supply.py

@@ -45,6 +45,11 @@ def test_get_total_supply(self, _make_id):
             self.assertEqual(expected_request, actual_request)
             self.assertTrue(result, supply)
 
+            # with height
+            self.icon_service.get_total_supply(height=self.setting['height'])
+            actual_request = json.loads(m._adapter.last_request.text)
+            self.assertEqual(hex(self.setting['height']), actual_request['params']['height'])
+
 
 if __name__ == "__main__":
     main()

tests/api_send/test_send_super.py

@@ -80,7 +80,8 @@ def setUpClass(cls):
             # It is used to send message only.
             "data": "0x" + "test".encode().hex(),
             "id": "0x" + os.urandom(32).hex(),
-            "timestamp": 10_000
+            "timestamp": 10_000,
+            "height": 100,
         }
 
 

tests/builder/test_call_builder.py

@@ -22,19 +22,21 @@ class TestCallBuilder(TestCase):
 
     def test_make_call_builder(self):
         """Testing for making a couple of call builders successfully"""
+        height = 100
 
         call_1 = CallBuilder() \
             .from_("1_FROM") \
             .to("1_TO") \
             .method("1_METHOD") \
             .params({"test": 123}) \
+            .height(height) \
             .build()
 
-        call_2 = CallBuilder().from_("2_FROM").to("2_TO").method("2_METHOD").params({"test": 123}).build()
+        call_2 = CallBuilder().from_("2_FROM").to("2_TO").method("2_METHOD").params({"test": 123}).height(100).build()
 
-        properties = ["from_", "to", "method", "params"]
-        values_call_1 = ["1_FROM", "1_TO", "1_METHOD", {'test': '0x7b'}]
-        values_call_2 = ["2_FROM", "2_TO", "2_METHOD", {'test': '0x7b'}]
+        properties = ["from_", "to", "method", "params", "height"]
+        values_call_1 = ["1_FROM", "1_TO", "1_METHOD", {'test': '0x7b'}, hex(height)]
+        values_call_2 = ["2_FROM", "2_TO", "2_METHOD", {'test': '0x7b'}, hex(height)]
 
         # Checks all of property is collect.
         for idx, property in enumerate(properties):
@@ -47,6 +49,7 @@ def test_make_call_builder_from_dict_to_dict(self):
             .to("1_TO") \
             .method("1_METHOD") \
             .params({"test": 123}) \
+            .height(100) \
             .build()
 
         call_1_as_dict = call_1.to_dict()