# Terra Instance

The Terra in the root of the jigu package represents your connection to a node running Terra Core, and is your main point of access for interacting with Terra APIs.

This document covers only getting connected through the Terra instance. Other facets will be covered separately, and given more dedicated treatment throughout the documentation.

# Connect to a node

jigu.Terra(chain_id, lcd_uri, ws_uri=None, gas_prices=None, gas_adjustment=None)

In order to interact with the Terra blockchain (reading data, broadcasting transactions, live calculation of fees, etc.), you will need to connect to a node that is connected to your desired network with its LCD (Lite Client Daemon) running.

from jigu import Terra
terra = Terra("columbus-3", "https://lcd.terra.dev")

# Parameters

str
chain_id

ID of blockchain to connect to.

TIP

If you want to use your node's chain id, you can set this field to None.

terra = Terra(None, "https://lcd.terra.dev")

str
lcd_url

HTTP / HTTPS URI of LCD Server of a running node.


str
ws_url
optional

WS / WSS URI of RPC server, for WebSockets.
Example: "ws://127.0.0.1:26657"


str
gas_prices
optional

Gas prices to use for automatic fee estimation.


DEFAULT Coins(uluna=0.015)
str
gas_adjustment
optional

Gas adjustment value to use for automatic fee estimation.


DEFAULT 1.4

TIP

It is conventional to assign the variable terra to the Terra instance representing your connection to a mainnet node, and another name such as soju for a Soju testnet node.

Jigu does not run a own node internally, one must already be running and be configured properly to work with a network. For production applications, you will want to create a Terra object and supply the URI of a node that is running the latest iteration of Columbus mainnet. To use a different network, such as the Soju testnet or a local testnet, you should provide the URI of a node connected to those networks.

Below is a list of official nodes for common networks you can connect to.

Network Chain ID Node URI
Columbus Mainnet columbus-3 https://lcd.terra.dev
Soju Testnet soju-0013 https://soju-lcd.terra.dev
Vodka Testnet vodka-0001 https://vodka-lcd.terra.dev

# Check your connection

Terra.is_connected()

You may want to check if you are properly connected. This function verifies that a connection can be made and that the node reports the proper chain ID.

if terra.is_connected():
    print(f"I am connected to {terra.chain_id}")
else:
    print("I am not connected!")

The Terra instance uses HTTP and does not maintain any form of persistent connection to the node. Instead, details about how to reach the node and which chain ID to use are saved, and HTTP requests are generated and dispatched as they are needed.

# Returns

bool

Whether or not the Terra instance was able to make a successful connection and retrieve the same Chain ID.

# Get TX info

Terra.tx_info(txhash)

Look a transaction up by its hash, which includes information about an included transaction such as its fee.

terra.tx_info("9097A4B1FE8E0356C38A1F2592C0C2BCFF0196631A9739259A0698E2948B3440")

# Parameters

str
txhash

Transaction's hash.


# Returns

TxInfo

The transaction information of the TX having the hash.

# Estimate transaction fee

Terra.estimate_fee(tx, gas_prices=None, gas_adjustment=None)

Simulate the transaction within the node to estimate how much gas and fees are needed for a transaction to be accepted. This will also find the necessary stability fee if one is required. By default, if you do not supply the gas_prices and gas_adjustment parameters, the values specified in the Terra instance will be used.

# you can set gas adjustment and gas prices to use
terra.gas_adjustment = 1.6
terra.gas_prices = Coins(uluna=0.02)

fee = terra.estimate_fee(tx)

# Parameters

StdSignMsg
tx

Transaction to estimate fee for.


Coins
gas_prices
optional

Gas prices to use for fee estimation. The node will try to find the combination of gas and fee amount such that your specified gas price will be met.


DEFAULT Terra.gas_prices
float
gas_adjustment
optional

Gas adjustment, a multiplicative factor to account for error.


DEFAULT Terra.gas_adjustment

# Returns

StdFee

Estimated fee.

# Broadcast transaction

Terra.broadcast(tx, mode="block")

Broadcasts a transaction to the blockchain, in one of three modes.

  • block will return after DeliverTx, when the transaction has been included in the next block.

  • sync will return after CheckTx, when the transaction has been verified by the node to be valid.

  • async will broadcast asynchronously, returning immediately.

# Parameters

StdTx
tx

Transaction to broadcast.


str
mode
optional

Transaction broadcasting mode. One of "block", "sync", or "async".


DEFAULT block

# Returns

TxBroadcastResult

Result of the transaction broadcast if successful.

# Get node information

Terra.node_info()

You can get information about the node you are connected to, which includes the version, proper chain_id, RPC address, etc.

# Returns

JiguBox with the following example's hierarchy:

Updated on: 3/10/2020, 5:07:35 PM