terra-money/LocalTerra

An instant, zero-config Terra blockchain and ecosystem.

What is LocalTerra?

LocalTerra is a complete Terra testnet and ecosystem containerized with Docker and orchestrated with a simple docker-compose file. It simplifies the way smart-contract developers test their contracts in a sandbox before they deploy them on a testnet or mainnet.

LocalTerra comes preconfigured with opinionated, sensible defaults for standard testing environments. If other projects mention testing on LocalTerra, they are referring to the settings defined in this repo.

LocalTerra has the following advantages over a public testnet:

• Easily modifiable world states
• Quick to reset for rapid iterations
• Simple simulations of different scenarios
• Controllable validator behavior

Prerequisites

• Docker
• docker-compose
• Supported known architecture: x86_64
• 16+ GB of RAM is recommended (for 8+ GB, Bombay testnet is recommended)

Install LocalTerra

1. Run the following commands::

$ git clone --depth 1 https://www.github.com/terra-money/LocalTerra
$ cd LocalTerra

2. Make sure your Docker daemon is running in the background and docker-compose is installed.

Start, stop, and reset LocalTerra

• Start LocalTerra:

$ docker-compose up

Your environment now contains:

• terrad RPC node running on tcp://localhost:26657
• LCD running on http://localhost:1317

Note: to run localterra with FCD use the docker-compose file from

• FCD

Stop LocalTerra:

$ docker-compose stop

Reset the world state:

$ docker-compose rm

Integrations

You can integrate LocalTerra in Terra Station, terrad, and the Terra JavaScript and Python SDKs.

Terra Station

Terra Station has built-in support for LocalTerra so that you can quickly and easily interact with it. Open Station, and switch to the Localterra network, as shown in the following image

terrad

Important: 'terracli' has been deprecated, and all of its functionalities are merged into 'terrad'.

1. Ensure the same version of terrad and LocalTerra are installed.

2. Use terrad to talk to your LocalTerra terrad node:

$ terrad status

This command automatically works because terrad connects to localhost:26657 by default.

The following command is the explicit form:

$ terrad status --node=tcp://localhost:26657

3. Run any of the terrad commands against your LocalTerra network, as shown in the following example:

$ terrad query account terra1dcegyrekltswvyy0xy69ydgxn9x8x32zdtapd8

Terra SDK for Python

Connect to the chain through LocalTerra's LCD server:

from terra_sdk.client.lcd import LCDClient
terra = LCDClient("localterra", "http://localhost:1317")

Terra SDK for JavaScript

Connect to the chain through LocalTerra's LCD server:

import { LCDClient } from "@terra-money/terra.js";

const terra = new LCDClient({
  URL: "http://localhost:1317",
  chainID: "localterra",
});

Configure LocalTerra

The majority of LocalTerra is implemented through a docker-compose.yml file, making it easily customizable. You can use LocalTerra as a starting template point for setting up your own local Terra testnet with Docker containers.

Out of the box, LocalTerra comes preconfigured with opinionated settings such as:

• ports defined for RPC (26657), LCD (1317) and FCD (3060)
• standard accounts

Modifying node configuration

You can modify the node configuration of your validator in the config/config.toml and config/app.toml files.

Pro tip: Speed Up Block Time

LocalTerra is often used alongside a script written with the Terra.js SDK or Terra Python SDK as a convenient way to do integration tests. You can greatly improve the experience by speeding up the block time.

To increase block time, edit the [consensus] parameters in the config/config.toml file, and specify your own values.

The following example configures all timeouts to 200ms:

##### consensus configuration options #####
[consensus]

wal_file = "data/cs.wal/wal"
- timeout_propose = "3s"
- timeout_propose_delta = "500ms"
- timeout_prevote = "1s"
- timeout_prevote_delta = "500ms"
- timeout_precommit_delta = "500ms"
- timeout_commit = "5s"
+ timeout_propose = "200ms"
+ timeout_propose_delta = "200ms"
+ timeout_prevote = "200ms"
+ timeout_prevote_delta = "200ms"
+ timeout_precommit_delta = "200ms"
+ timeout_commit = "200ms"

Additionally, you can use the following single line to configure timeouts:

sed -E -i '/timeout_(propose|prevote|precommit|commit)/s/[0-9]+m?s/200ms/' config/config.toml

Modifying genesis

You can change the genesis.json file by altering config/genesis.json. To load your changes, restart your LocalTerra.

Accounts

LocalTerra is pre-configured with one validator and 10 accounts with LUNA balances.

Contracts

There are 10 contracts already deployed on genesis:

License

This software is licensed under the MIT license.

© 2020 Terraform Labs, PTE.