Mospy Tutorial #1 — The Basics

Mospy is a Python library for interacting with currencies based on the Cosmos sdk. In this series of tutorials we will explore everything you can do with the library. This is the first episode, so we will start at the beginning. Our goal in this article is to send a transaction to the Cosmos chain to send 1 ATOM from our wallet to someone else.

Setup

Mospy is hosted on pypi which means you can use pip to install it:
pip install mospy-wallet

If you prefer to build it by yourself you can use the github repository
pip install git+https://github.com/ctrl-Felix/mospy.git

Setting up your Account

The first thing you will probably want to do is to setup your wallet to be able to sign transactions with it. To do this with mospy we need to use the Account class which can be imported with from mospy import Account. The Account takes a lot of parameters but many of them are optional and we will cover this in detail later. The first step we need to do now is to initialise the Account which can be done as following:

from mospy import Account

account = Account(
      seed_phrase="law grab theory ..."
)

Alternatively you can also use a private key:

from mospy import Account

account = Account(
      private_key="8c2..." # Note: no 0x at the beginning of the private key
)

Configuring the Account parameters

Having created the account, we now need to set the correct account number and sequence. These two values can be queried via the Cosmos API. I covered this in an earlier article. Once you have retrieved them yourself, you can set them manually:

account.next_sequence = <your sequence here>
account.account_number = <your account number here>

Otherwise you can use the built-in HTTPClient which can also query these parameters for you. Either way, you’ll probably need an api endpoint now, so I suggest you check out https://cosmos.directory/cosmoshub/nodes to find an api endpoint if you don’t already have one. I will be using my own endpoint https://api.cosmos.interbloc.org for this example. Once you have your api endpoint, you can instantiate the HTTPClient and query your account parameters using the following code:

from mospy.clients import HTTPClient

client = HTTPClient(
    api="https://api.cosmos.interbloc.org" 
)

# query and set the account parameters
client.load_account_data(account=account)

Either way, the account parameters are now set and we can get on with sending your first transaction!

Creating a Transaction

For this example we will create a transaction and send 1 ATOM to another address. The first thing we need to do is instantiate the Transaction class. To do this we also need to define the gas required for this transaction. A send transaction on cosmos will probably require about 70,000 gas, so we can set it to 85,000 to have some margin. You will need to increase this value if you want to send more complex transactions.

from mospy import Transaction

tx = Transaction(
  account=account,
  gas=85000
)

After creating our transaction object, we need to add the send message to it. To do this we can use the add_msg function. Note that the on-chain denomination for Cosmos is uatom. This represents the smallest unit of a token. To send 1 ATOM you must send 1,000,000 uatom. The tx_type for this transaction is transfer. We will cover this in more detail in another article.

tx.add_msg(
    tx_type='transfer',
    sender=account,
    receipient="cosmos1...recipient...",
    amount=1000000,
    denom="uatom"
)

Now that we have added the message to the transaction, we need to set our fee. There is a helper function for this called set_fee. The set_fee function also takes a denom and an amount, so we need to pass uatom again. A good fee for cosmos right now is 2500 uatom (0.002500 ATOM), so all we need to do is add the following code:

tx.set_fee(
    denom="uatom",
    amount=2500
)

After doing these steps our transaction object is now ready and we can continue with broadcasting it.

Broadcasting a Transaction

There are two different ways to send a transaction with mospy. You can send the transaction manually through the Cosmos RPC/API. The following code shows you the structure of the payload you need to send:

# Get the transaction bytes
tx_bytes = tx.get_tx_bytes_as_string()

# Submit the transaction through the Tendermint RPC
rpc_url = "https://rpc.cosmos.interbloc.org/"
pushable_tx = json.dumps(
              {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "broadcast_tx_sync", # Available methods: broadcast_tx_sync, broadcast_tx_async, broadcast_tx_commit
                "params": {
                    "tx": tx_bytes
                }
              }
            )
r = httpx.post(rpc_url, data=pushable_tx)

# Submit the transaction through the Cosmos REST API
rpc_api = "https://api.cosmos.network/cosmos/tx/v1beta1/txs"
pushable_tx = json.dumps(
                {
                  "tx_bytes": tx_bytes,
                  "mode": "BROADCAST_MODE_SYNC" # Available modes: BROADCAST_MODE_SYNC, BROADCAST_MODE_ASYNC, BROADCAST_MODE_BLOCK
                }
              )
r = httpx.post(rpc_api, data=pushable_tx)

Alternatively, you can use the HTTPClient again, which can also send a transaction for you:

hash, code, log = client.broadcast_transaction(transaction=tx)

Either way, you are now able to send transactions in python!

If you have questions or need more help feel free to leave a comment and I will get back to you asap. Otherwise you can also create a issue on https://github.com/ctrl-Felix/mospy.