Merge pull request #10 from AstroWa3l/main

New update to match  Koios API v1.0.10 release with added endpoints and removed deprecated

koios_1_0_10_changes.md

@@ -0,0 +1,46 @@
+## Changes for KOIOS API
+
+- In this file you will find the changes we need to complete to koios_python before next release to match the current version of KOIOS API. All tasks that have been completed are the ones crossed out by a line.
+
+### Deprecations
+
+- ~~`/asset_address_list` - Renamed to asset_addresses keeping naming line with other endpoints (old endpoint will be retired in future release) #149~~
+- ~~`/asset_policy_info` - Renamed to policy_asset_info keeping naming line with other endpoints (old endpoint will be retired in future release) #149~~
+
+### New endpoints added
+
+- ~~`/asset_addresses` - Equivalent of deprecated /asset_address_list #149~~
+- ~~`/asset_nft_address` - Returns address where the specified NFT sits on #149~~
+- ~~`/account_utxos` - Returns brief details on non-empty UTxOs associated with a given stake address #149~~
+- ~~`/asset_info_bulk` - Bulk version of /asset_info #142~~
+- ~~`/asset_token_registry` - Returns assets registered via token registry on github #145~~
+- ~~`/credential_utxos` - Returns UTxOs associated with a payment credential #149~~
+- ~~`/param_updates` - Returns list of parameter update proposals applied to the network #149~~
+- ~~`/policy_asset_addresses` - Returns addresses with quantity for each asset on a given policy #149~~
+- ~~`/policy_asset_info` - Equivalent of deprecated /asset_policy_info but with more details in output #149~~
+- ~~`/policy_asset_list` - Returns list of asset under the given policy (including supply) #142, #149~~
+
+
+## Data Input/Output Changes
+- Input - `/account_addresses` - Add optional _first_only and _empty flags to show only first address with tx or to include empty addresses to output #149
+- Input - `/epoch_info` - Add optional _include_next_epoch field to show next epoch stats if available (eg: nonce, active stake) #143
+- Output (addition) - `/account_assets` , `/address_assets` , `/address_info`, `/tx_info`, `/tx_utxos` - Add decimals to output #142
+- Output (addition) - `/policy_asset_info` - Add `minting_tx_hash`, `total_supply`, `mint_cnt`, `burn_cnt` and `creation_time` fields to the output #149
+- Output (breaking) - `/tx_info` - Change `_invalid_before` and `_invalid_after` to text field #141
+- Output (breaking/removal) - `tx_info` - Remove the field `plutus_contracts` > [array] > `outputs` as there is no logic to connect it to inputs spending #163
+
+## Chores/epoch_info, /epoch_params - Restrict output to current epoch #149
+- `/block_info` - Use `/previous_id` field to show previous/next blocks (previously was using block_id/height) #145
+- `/asset_info/asset_policy_info` - Fix mint tx data to be latest #141
+- Support new guild scripts revamp #1572
+- Add asset token registry check 1606
+- New cache table `grest.asset_info_cache` to hold mint/burn counts alongwith first/last mint tx/keys #142
+- Bump to Koios 1.0.10rc #149
+- Fix typo in specs for `/pool_delegators` output column `latest_delegation_tx_hash` #149
+- Add indexes for ones missing after configuring cardano-db-sync 13.1.0.0 #149
+- Update PostgREST to be run as `authenticator` user, whose default `statement_timeout` is set to 65s and update configs accordingly #1606
+- Replace all RPC references for JSON endpoints with JSONB, this allows filtering child members of array elements using `cs.[{"key":"value"}]` in PostgREST #172
+- Fix Asset Info Cache to not rely on being able to decode policy ID (bad data on IO repo) #173
+- Handle Pool_list to check metadata entries that have not been populated in pool_offline_data #173
+- Fix pool_updates to use pmr_id instead of pool_offline_data.id #173
+- Update account_info_cached description to clarify it is effective for registered accounts #173

koios_python/account.py

@@ -18,9 +18,9 @@ def get_account_list(self, content_range="0-999"):
     """
     timeout = get_timeout()
     custom_headers = {"Range": str(content_range)}
-    address_list = requests.get(self.ACCOUNT_LIST_URL, headers = custom_headers, timeout=timeout)
-    address_list = json.loads(address_list.content)
-    return address_list
+    account_list = requests.get(self.ACCOUNT_LIST_URL, headers = custom_headers, timeout=timeout)
+    account_list = json.loads(account_list.content)
+    return account_list
 
 
 @Exception_Handler
@@ -39,6 +39,20 @@ def get_account_info(self, *args):
     return accounts_info
 
 
+@Exception_Handler
+def get_account_utxos(self, stake):
+    """
+    Get a list of all UTxOs for a given stake address (account)
+
+    :return: string list Array of account UTxOs associated with stake address.
+    :rtype: list.
+    """
+    timeout = get_timeout()
+    account_utxos = requests.get(f"{self.ACCOUNT_UTXOS_URL}{stake}", timeout=timeout)
+    account_utxos = json.loads(account_utxos.content)
+    return account_utxos
+
+
 @Exception_Handler
 def get_account_info_cached(self, *args):
     """
@@ -50,7 +64,7 @@ def get_account_info_cached(self, *args):
     """
     timeout = get_timeout()
     get_format = {"_stake_addresses": [args] }
-    accounts_info = requests.post(self.ACCOUNT_INFO_URL_CACHED, json= get_format,timeout=timeout)
+    accounts_info = requests.post(self.ACCOUNT_INFO_CACHED_URL, json=get_format, timeout=timeout)
     accounts_info = json.loads(accounts_info.content)
     return accounts_info
 
@@ -126,7 +140,7 @@ def get_account_assets(self, *args):
 
 
 ## Alternative to Paginate all list automatically
-def get_account_assets_2(self, *args):
+def get_account_assets_paginated(self, *args):
     """
     Get the native asset balance of given accounts.
     :param str args: staking address/es in bech32 format (stake1...)

koios_python/address.py

@@ -25,7 +25,7 @@ def get_address_info(self, *args):
 
 
 @Exception_Handler
-def get_address_txs(self, address_tx, after_block=0):
+def get_address_txs(self, *address_tx, after_block=0):
     """
     Get the transaction hash list of input address array, optionally filtering after specified
     block height (inclusive)
@@ -41,6 +41,23 @@ def get_address_txs(self, address_tx, after_block=0):
 
     return hash_list
 
+@Exception_Handler
+def get_credential_utxos(self, *payment_credentials, content_range="0-5"):
+    """
+    Get a list of UTxO against input payment credential array including their balances.
+    
+    :param str payment_credentials
+    :return: list of utxos
+    :rtype: list.
+    """
+    timeout = get_timeout()
+    custom_headers = {"Range": str(content_range)}
+    get_format = {"_payment_credentials":[payment_credentials]}
+    utxos = requests.post(self.ADDRESS_CREDENTIAL_UTXOS_URL, json = get_format, headers = custom_headers, timeout=timeout)
+    utxos = json.loads(utxos.content)
+
+    return utxos
+
 
 @Exception_Handler
 def get_address_assets(self, *args):
@@ -60,7 +77,7 @@ def get_address_assets(self, *args):
 
 
 @Exception_Handler
-def get_credential_txs(self, payment_credentials, after_block=0):
+def get_credential_txs(self, *payment_credentials, after_block=0, content_range="0-15"):
     """
     Get the transaction hash list of input payment credential array (stake key), optionally
     filtering after specified block height (inclusive).
@@ -71,8 +88,9 @@ def get_credential_txs(self, payment_credentials, after_block=0):
     :rtype: list.
     """
     timeout = get_timeout()
-    get_format = {"_payment_credentials":[payment_credentials], "_after_block_height": after_block}
-    hash_list = requests.post(self.CREDENTIAL_TXS_URL, json = get_format, timeout=timeout)
+    custom_headers = {"Range": str(content_range)}
+    get_format = {"_payment_credentials": [payment_credentials], "_after_block_height": after_block}
+    hash_list = requests.post(self.ADDRESS_CREDENTIAL_TXS_URL, json = get_format, headers=custom_headers, timeout=timeout)
     hash_list  = json.loads(hash_list.content)
 
-    return hash_list
+    return hash_list

koios_python/asset.py

@@ -21,9 +21,23 @@ def get_asset_list(self, content_range="0-999"):
     asset_list = json.loads(asset_list.content)
     return asset_list
 
+@Exception_Handler
+def get_asset_token_registry(self, content_range="0-999"):
+    """
+    Get a list of assets registered via token registry on github
+
+    :return: list of all asset token registry.
+    :rtype: list.    
+    """
+    timeout = get_timeout()
+    custom_headers = {"Range": str(content_range)}
+    token_registry = requests.get(self.ASSET_TOKEN_REGISTRY_URL, headers = custom_headers, timeout=timeout)
+    token_registry = json.loads(token_registry.content)
+    return token_registry
+
 
 @Exception_Handler
-def get_asset_address_list(self, asset_policy, asset_name, content_range="0-999"):
+def get_asset_addresses(self, asset_policy, asset_name, content_range="0-999"):
     """
     Get the list of all addresses holding a given asset.
 
@@ -34,11 +48,26 @@ def get_asset_address_list(self, asset_policy, asset_name, content_range="0-999"
     """
     timeout = get_timeout()
     custom_headers = {"Range": str(content_range)}
-    info = requests.get(f"{self.ASSET_ADDRESS_LIST_URL}{asset_policy}&_asset_name={asset_name}", \
+    info = requests.get(f"{self.ASSET_ADDRESSES_URL}{asset_policy}&_asset_name={asset_name}", \
         headers = custom_headers, timeout=timeout)
     info = json.loads(info.content)
     return info
 
+@Exception_Handler
+def get_asset_nft_address(self, asset_policy, asset_name):
+    """
+    Get the address where specified NFT currently reside on.
+
+    :param str asset_policy: asset Policy ID in hexadecimal format (hex).
+    :param str asset_name: string with Asset Name in hexadecimal format (hex).
+    :return: list with payment addresses.
+    :rtype: list.
+    """
+    timeout = get_timeout()
+    info = requests.get(f"{self.ASSET_NFT_ADDRESS_URL}{asset_policy}&_asset_name={asset_name}", timeout=timeout)
+    info = json.loads(info.content)
+    return info
+
 
 @Exception_Handler
 def get_asset_info(self, asset_policy, asset_name):
@@ -55,6 +84,21 @@ def get_asset_info(self, asset_policy, asset_name):
     info = json.loads(info.content)
     return info
 
+@Exception_Handler
+def get_asset_info_bulk(self, *asset_list):
+    """
+    Get the information of a list of assets including first minting & token registry metadata.
+    :param list asset_list: list of assets to query.
+    :return: list of all asset info.
+    :rtype: list.
+    """
+    timeout = get_timeout()
+    get_format = {"_asset_list": asset_list}
+    asset_info = requests.post(self.ASSET_INFO_BULK_URL, json= get_format, timeout=timeout)
+    asset_info = json.loads(asset_info.content)
+
+    return asset_info
+
 
 @Exception_Handler
 def get_asset_history(self, asset_policy, asset_name):
@@ -71,9 +115,24 @@ def get_asset_history(self, asset_policy, asset_name):
     history = json.loads(history.content)
     return history
 
+@Exception_Handler
+def get_policy_asset_addresses(self, asset_policy, content_range="0-420"):
+    """
+   Get the list of addresses with quantity for each asset on the given policy
+
+    :param str asset_policy: asset Policy ID in hexadecimal format (hex).
+    :return: list of all addresses.
+    :rtype: list.
+    """
+    timeout = get_timeout()
+    custom_headers = {"Range": str(content_range)}
+    info = requests.get(f"{self.POLICY_ASSET_ADDRESSES_LIST_URL}{asset_policy}", headers=custom_headers, timeout=timeout)
+    info = json.loads(info.content)
+    return info
+
 
 @Exception_Handler
-def get_asset_policy_info(self, asset_policy):
+def get_policy_asset_info(self, asset_policy):
     """
     Get the information for all assets under the same policy.
 
@@ -82,7 +141,22 @@ def get_asset_policy_info(self, asset_policy):
     :rtype: list.
     """
     timeout = get_timeout()
-    info = requests.get(f"{self.ASSET_POLICY_INFO_URL}{asset_policy}", timeout=timeout)
+    info = requests.get(f"{self.POLICY_ASSET_INFO_URL}{asset_policy}", timeout=timeout)
+    info = json.loads(info.content)
+    return info
+
+
+@Exception_Handler
+def get_policy_asset_list(self, asset_policy):
+    """
+    Get the list of asset under the given policy (including balances)
+
+    :param str asset_policy: asset Policy ID in hexadecimal format (hex).
+    :return: list of all assets under the same policy.
+    :rtype: list.
+    """
+    timeout = get_timeout()
+    info = requests.get(f"{self.POLICY_ASSET_LIST_URL}{asset_policy}", timeout=timeout)
     info = json.loads(info.content)
     return info
 
@@ -105,17 +179,23 @@ def get_asset_summary(self, asset_policy, asset_name):
 
 
 @Exception_Handler
-def get_asset_txs(self, asset_policy, asset_name, after_block_height=0):
+def get_asset_txs(self, asset_policy, asset_name, after_block_height=0, history=False, content_range="0-515"):
     """
-    Get the list of all asset transaction hashes (newest first).
+    Get the list of asset under the given policy (including balances)
 
     :param str asset_policy: asset Policy ID in hexadecimal format (hex).
-    :param str asset_name: string with Asset Name in hexadecimal format (hex).
-    :param int after_block_height: Block height for specifying time delta, if not data start from 0
-    :return: list of all asset hashes transactions.
+    :return: list of all assets under the same policy.
     :rtype: list.
     """
     timeout = get_timeout()
-    txs = requests.get(f"{self.ASSET_TXS_URL}{asset_policy}&_asset_name={asset_name}&_after_block_height={after_block_height}", timeout=timeout)
-    txs = json.loads(txs.content)
-    return txs
+    custom_headers = {"Range": str(content_range)}
+
+    if history == True:
+        history = "true"
+        txs = requests.get(f"{self.ASSET_TXS_URL}{asset_policy}&_asset_name={asset_name}&_after_block_height={after_block_height}&_history={history}", headers=custom_headers, timeout=timeout)
+        txs = json.loads(txs.content)
+    if history == False:
+        history = "false"
+        txs = requests.get(f"{self.ASSET_TXS_URL}{asset_policy}&_asset_name={asset_name}&_after_block_height={after_block_height}&_history={history}", headers=custom_headers, timeout=timeout)
+        txs = json.loads(txs.content)
+    return txs

koios_python/epoch.py

@@ -7,7 +7,7 @@
 from .environment import *
 
 @Exception_Handler
-def get_epoch_info(self, epoch_no=None):
+def get_epoch_info(self, epoch_no=None, include_next_epoch=False):
     """
     Get the epoch information, all epochs if no epoch specified.
 
@@ -16,15 +16,21 @@ def get_epoch_info(self, epoch_no=None):
     :rtype: list
     """
     timeout = get_timeout()
-    if epoch_no is None:
-        info = requests.get(self.EPOCH_INFO_URL)
-        print(self.EPOCH_INFO_URL)
+    if epoch_no is None and include_next_epoch is False:
+        info = requests.get(f"{self.EPOCH_INFO_URL}?_include_next_epoch=false", timeout=timeout)
         info = json.loads(info.content)
-    else:
-        info = requests.get(f"{self.EPOCH_INFO_URL}?_epoch_no={epoch_no}", timeout=timeout)
-        print(self.EPOCH_INFO_URL)
+    if epoch_no is None and include_next_epoch is True:
+        info = requests.get(f"{self.EPOCH_INFO_URL}?_include_next_epoch=true", timeout=timeout)
+        info = json.loads(info.content)
+    if epoch_no is not None and include_next_epoch is False:
+        info = requests.get(f"{self.EPOCH_INFO_URL}?_epoch_no={epoch_no}&_include_next_epoch=false",\
+                            timeout=timeout)
         info = json.loads(info.content)
-    return info 
+    if epoch_no is not None and include_next_epoch is True:
+        info = requests.get(f"{self.EPOCH_INFO_URL}?_epoch_no={epoch_no}&_include_next_epoch=true",\
+                             timeout=timeout)
+        info = json.loads(info.content)
+    return info
 
 
 @Exception_Handler
@@ -39,7 +45,7 @@ def get_epoch_params(self, epoch_no=None):
     """
     timeout = get_timeout()
     if epoch_no is None:
-        info = requests.get(self.EPOCH_PARAMS_URL)
+        info = requests.get(self.EPOCH_PARAMS_URL, timeout=timeout)
         info = json.loads(info.content)
     else:
         info = requests.get(f"{self.EPOCH_PARAMS_URL}?_epoch_no={epoch_no}", timeout=timeout)
@@ -58,7 +64,7 @@ def get_epoch_block_protocols(self, epoch_no=None):
     """
     timeout = get_timeout()
     if epoch_no is None:
-        info = requests.get(self.EPOCH_BLOCKS_URL)
+        info = requests.get(self.EPOCH_BLOCKS_URL, timeout=timeout)
         info = json.loads(info.content)
     else:
         info = requests.get(f"{self.EPOCH_BLOCKS_URL}?_epoch_no={epoch_no}", timeout=timeout)

koios_python/network.py

@@ -33,6 +33,7 @@ def get_genesis(self):
     genesis = json.loads(genesis.content)
     return genesis
 
+
 @Exception_Handler
 def get_totals(self, epoch_no=None):
     """
@@ -50,4 +51,19 @@ def get_totals(self, epoch_no=None):
     else:
         totals = requests.get(f"{self.TOTALS_URL}?_epoch_no={epoch_no}", timeout=timeout)
         totals = json.loads(totals.content)
-    return totals
+    return totals
+
+@Exception_Handler
+def get_param_updates(self, content_range="0-57"):
+    """
+    Get all parameter update proposals submitted to the chain starting Shelley era
+
+    :return: list of protocol parameters starting from Shelley era.
+    :rtype: list
+    """
+    timeout = get_timeout()
+    custom_headers = {"Range": str(content_range)}
+    network_params = requests.get(self.NETWORK_PARAM_UPDATES_URL, headers=custom_headers, timeout=timeout)
+    network_params = json.loads(network_params.content)
+    return network_params
+