Docs revisions (fetchai#149)

* improved landing page and fixed typo * made ATOM example \'work\' and added link to other chain info * added function to query all coin balances associated with an address * documentation for balance queries * more detailed balance querying instructions * update to docs to include multi-token queries * now passing (pedantic) formatting check * now passing isort test :( * updated readme/makefile and fixed typo * minor change * update makefile and readme * minor change Co-authored-by: ali <[email protected]>
Galadrin · May 11, 2022 · 4a66936 · 4a66936
1 parent 4e6d237
commit 4a66936
Show file tree

Hide file tree

Showing 7 changed files with 70 additions and 50 deletions.
diff --git a/Makefile b/Makefile
@@ -166,6 +166,11 @@ copyright-check:
 docs:
  mkdocs build --clean
 
+
+.PHONY: docs-live
+open-docs:
+ mkdocs serve
+
 ####################
 ### Clean and init commands
 ####################

diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@
  <img alt="PyPI - Wheel" src="https://img.shields.io/pypi/wheel/cosmpy">
  </a>
  <a href="https://github.com/fetchai/cosmpy/blob/main/LICENSE">
- <img alt="License" src="https://img.shields.io/pypi/l/cosmpy"> 
+ <img alt="License" src="https://img.shields.io/pypi/l/cosmpy">
  </a>
 </p>
 <p align="center">
@@ -45,56 +45,45 @@ A python library for interacting with cosmos based blockchain networks
 
 ## Installing
 
-To install the project use:
+To install the library use:
 
- pip3 install cosmpy
+```bash
+pip3 install cosmpy
+```
 
-## Getting started
+## Getting Started
 
-Below is a simple example for querying an account's balance and sending funds from one account to another using `RestClient`:
+Below is a simple example for querying an account's balances:
 
- from cosmpy.clients.ledger import CosmosLedger
- from cosmpy.clients.crypto import CosmosCrypto, Coin
+```python
+from cosmpy.aerial.client import LedgerClient, NetworkConfig
 
- # Data
- rest_node_address = "https://the_rest_endpoint"
- alice_crypto = CosmosCrypto(private_key_str="<private_key_in_hex_format>"))
- chain_id = "some_chain_id"
- denom = "some_denomination"
- bob_address = "some_address"
+# connect to Fetch.ai network using default parameters
+ledger_client = LedgerClient(NetworkConfig.fetchai_mainnet())
 
- ledger = CosmosLedger(chain_id=chain_id, rest_node_address=rest_endpoint_addres)
-
- # Query Alice's Balance
- res = ledger.get_balance(alice_crypto.get_address(), denom)
- print(f"Alice's Balance: {res} {denom}")
-
- # Send 1 <denom> from Alice to Bob
- ledger.send_tokens(alice_crypto, bob_address, [Coin(amount="1", denom=denom)])
+alice: str = 'fetch12q5gw9l9d0yyq2th77x6pjsesczpsly8h5089x'
+balances = ledger_client.query_bank_all_balances(alice)
+
+# show all coin balances
+for coin in balances:
+ print(f'{coin.amount}{coin.denom}')
+```
 
 ## Documentation
 
-To see the documentation, first run:
+To see the documentation:
 
 ```bash
-make generate-docs
+make docs-live
 ```
 
-Then (if on Linux or MacOS):
+Then navigate to the following URL in your browser: 
 
-```bash
-make open-docs
-```
-
-And if on windows, open `docs/build/html/index.html`.
+[https://127.0.0.1:8000/cosmpy/](https://127.0.0.1:8000/cosmpy/)
 
 ## Examples
 
-Under the `examples` directory, you can find examples of basic ledger interactions with `cosmpy` using both REST and gRPC, e.g. querying, sending a transaction, interacting with a smart contract, and performing atomic swaps. To run any example `<example_file_name>`: 
-
- ```bash
- python ./examples/<example_file_name>.py
- ```
+Under the `examples` directory, you can find examples of basic ledger interactions using `cosmpy` e.g. transferring tokens, staking, deployinig and interacting with a smart contract, and performing atomic swaps.
 
 ## Extra Resources
 

diff --git a/cosmpy/aerial/client/__init__.py b/cosmpy/aerial/client/__init__.py
@@ -51,7 +51,10 @@
 from cosmpy.protos.cosmos.auth.v1beta1.auth_pb2 import BaseAccount
 from cosmpy.protos.cosmos.auth.v1beta1.query_pb2 import QueryAccountRequest
 from cosmpy.protos.cosmos.auth.v1beta1.query_pb2_grpc import QueryStub as AuthGrpcClient
-from cosmpy.protos.cosmos.bank.v1beta1.query_pb2 import QueryBalanceRequest
+from cosmpy.protos.cosmos.bank.v1beta1.query_pb2 import (
+ QueryAllBalancesRequest,
+ QueryBalanceRequest,
+)
 from cosmpy.protos.cosmos.bank.v1beta1.query_pb2_grpc import QueryStub as BankGrpcClient
 from cosmpy.protos.cosmos.distribution.v1beta1.query_pb2 import (
  QueryDelegationRewardsRequest,
@@ -117,6 +120,12 @@ class Validator:
  status: ValidatorStatus
 
 
+@dataclass
+class Coin:
+ amount: int
+ denom: str
+
+
 @dataclass
 class StakingSummary:
  current_positions: List[StakingPosition]
@@ -219,6 +228,13 @@ def query_bank_balance(self, address: Address, denom: Optional[str] = None) -> i
 
  return int(resp.balance.amount)
 
+ def query_bank_all_balances(self, address: Address) -> List[Coin]:
+
+ req = QueryAllBalancesRequest(address=str(address))
+ resp = self.bank.AllBalances(req)
+
+ return [Coin(amount=coin.amount, denom=coin.denom) for coin in resp.balances]
+
  def send_tokens(
  self,
  destination: Address,

diff --git a/docs/connect-to-network.md b/docs/connect-to-network.md
@@ -8,16 +8,18 @@ from cosmpy.aerial.client import LedgerClient, NetworkConfig
 ledger_client = LedgerClient(NetworkConfig.fetch_mainnet())
 ```
 
-For convenience, some networks' configurations are provided automatically. For example, `NetworkConfig.fetch_mainnet()` is the configuration for the Fetch ledger. If you want to target other chains, you can customise `NetworkConfig` as shown in the example below:
+For convenience, some networks' configurations are provided automatically. For example, `NetworkConfig.fetch_mainnet()` is the configuration for the Fetch ledger. If you want to interact with other chains, you can customise `NetworkConfig` as shown in the example below:
 
 ```python
 cfg = NetworkConfig(
  chain_id="cosmoshub-4",
- url="grpc+https://...",
+ url="grpc+https://grpc-cosmoshub.blockapsis.com:429",
  fee_minimum_gas_price=1,
  fee_denomination="uatom",
  staking_denomination="uatom",
 )
 
-ledger = LedgerClient(cfg)
+ledger_client = LedgerClient(cfg)
 ```
+
+A full list of chain identifiers, denominations and end-points can be found at the Cosmos [chain registry](https://github.com/cosmos/chain-registry/).
diff --git a/docs/index.md b/docs/index.md
@@ -1,8 +1,8 @@
 Cosmpy is a Python library for interacting with Cosmos-based blockchains.
 
-* A simplified Cosmos SDK agnostic API for basic chain operations.
-* An easy API for deploying and interacting with CosmWasm-based smart contracts.
-* Low-level access to primitive ledger APIs if required.
+* A simplified command line tool for querying and sending transactions to Cosmos-SDK blockchains. 
+* Features an easy interface for deploying and interacting with Cosmwasm smart contracts.
+* Provides access to lower-level ledger APIs for advanced use-cases. 
 
 ## To install
 
@@ -17,7 +17,7 @@ pip3 install cosmpy
 ## Repository
 
 ```
-https://github.com/fetchai/cosmpy`
+https://github.com/fetchai/cosmpy
 ```
 
 ## To contribute

diff --git a/docs/query-balance.md b/docs/query-balance.md
@@ -1,15 +1,23 @@
-# ️Querying balance
+# ️Querying balances
 
-To query the balance of an account using a [`LedgerClient`](connect-to-network.md) object `ledger_client`:
+A [`LedgerClient`](connect-to-network.md) object can be used to query the balances associated with a particular address:
 
 ```python
-balance = ledger_client.query_bank_balance('fetch1h2l3cnu7e23whmd5yrfeunacez9tv0plv5rxqy')
+address: str = 'fetch12q5gw9l9d0yyq2th77x6pjsesczpsly8h5089x'
+balances = ledger_client.query_bank_all_balances(address)
 ```
 
-`fetch1h2l3cnu7e23whmd5yrfeunacez9tv0plv5rxqy` in the above code is the account's address.
+This will return a `List` of `Coin` objects that contain `amount` and `denom` variables that correspond to all of the funds held at the address and their denominations. This list includes all natively defined coins along with any tokens transferred using the inter-blockchain communication ([IBC](https://ibcprotocol.org/)) protocol. 
 
-By default, this will query the fee denomination that is in the network config associated with `ledger_client`. To explicitly specify the denomination value:
+```python
+>>> balances
+[Coin(amount='29263221445595384075', denom='afet')]
+```
+
+It's also possible to query the funds associated with a particular denomination by calling 
 
 ```python
-balance = ledger_client.query_bank_balance('cosmos1h2l3cnu7e23whmd5yrfeunacez9tv0plv5rxqy', denom='uatom')
-```
+balance = ledger_client.query_bank_balance(address, denom='afet')
+```
+
+which will return the value of the (integer) funds held by the address with the specified denomination. If the `denom` argument is omitted the function will return the fee denomination specified in the `NetworkConfig` object used to initialise the `LedgerClient`.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -8,7 +8,7 @@ nav:
  - Getting started: 'index.md'
  - Beginner:
  - Connect to a network: 'connect-to-network.md'
- - Query the balance: 'query-balance.md'
+ - Querying balances: 'query-balance.md'
  - Wallets and Keys: 'wallets-and-keys.md'
  - Send tokens: 'send-tokens.md'
  - Staking: 'staking.md'