var img = document.createElement('img'); img.src = "https://terradocs.matomo.cloud//piwik.php?idsite=1&rec=1&url=https://docs.terra.money" + location.pathname; img.style = "border:0"; img.alt = "tracker"; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(img,s);
Skip to main content

Use Terrain with LocalTerra

LocalTerra is a complete Terra testnet and ecosystem containerized with Docker. Use LocalTerra to simulate transactions in a test environment.

Prerequisites​

☢️Node version error

Use LTS Node.js 16 if you encounter the following error code.
error:0308010C:digital envelope routines::unsupported

ℹ️Running NPM on M1 Macs
Click here for details.

Some M1 macs may need to use the latest LTS version of Node to complete this tutorial. Consider using a node version manager such as nvm. After installing nvm, run the following commands to install and then switch to the latest LTS version of node.


_2
nvm install --lts
_2
nvm use --lts

The nvm use --lts command will need to be run every time you open a new terminal to use the LTS version of node.

To default to the LTS version of node when restarting your terminal, run the following:


_1
nvm alias default <desired-node-version>

Install and run LocalTerra​

  1. Download LocalTerra.
install-LocalTerra
Copy

_3
git clone --depth 1 https://github.com/terra-money/localterra
_3
cd localterra
_3
docker-compose up

  1. Start LocalTerra.
install-LocalTerra
Copy

_3
git clone --depth 1 https://github.com/terra-money/localterra
_3
cd localterra
_3
docker-compose up

  1. You will start seeing LocalTerra block activity in your terminal. Keep LocalTerra running while you perform the next steps in a new terminal window.
install-LocalTerra
Copy

_3
git clone --depth 1 https://github.com/terra-money/localterra
_3
cd localterra
_3
docker-compose up

  1. Download LocalTerra.
  1. Start LocalTerra.
  1. You will start seeing LocalTerra block activity in your terminal. Keep LocalTerra running while you perform the next steps in a new terminal window.
install-LocalTerra
CopyExpandClose

_3
git clone --depth 1 https://github.com/terra-money/localterra
_3
cd localterra
_3
docker-compose up

💡LocalTerra Accounts

To view LocalTerra wallet information, visit the LocalTerra accounts page. For more configuration options, visit the LocalTerra configuration page.

Counter tutorial

After installing LocalTerra, you are ready to use Terrain. This short tutorial walks you through setting up your project and creating a simple counter that increments upon request.

1. Scaffold your dApp​

With Terrain installed, you can now scaffold a template application in a new terminal window.

  1. Create a new dApp project.

_1
terrain new my_terra_dapp

  1. Change directory into your newly scaffolded dApp.

_1
cd my_terra_dapp

Project structure​

Your scaffolded project will have the following structure.


_10
.
_10
├── contracts # The contracts' source code.
_10
│ ├── my_terra_dapp
_10
│ └── ... # Add more contracts here.
_10
├── frontend # The front-end application.
_10
├── lib # Predefined functions for task and console.
_10
├── tasks # Predefined tasks.
_10
├── keys.terrain.js # Keys for signing transactions.
_10
├── config.terrain.json # Config for connections and contract deployments.
_10
└── refs.terrain.json # Deployed code and contract references.

2. Deploy​

To deploy the application, run the following command in your terminal.


_1
terrain deploy my_terra_dapp

The deploy command performs the following steps automatically.

  • Builds the smart contract.
  • Optimizes the smart contract.
  • Uploads the smart contract to LocalTerra.
  • Instantiates the deployed smart contract.
💡Increase Docker memory

If you are running LocalTerra and the previous deploy command is not working, try increasing Docker's memory allowance. You can do this by clicking on the Docker icon, clicking on Preferences and then navigating to Resources. Increase the memory to at least 4 GB and then click Apply & Restart. You can then try running the deploy command again. If you are still having trouble with deploying your dApp, you can try increasing the memory to 6 GB.

3. Generate TypeScript client​

Terrain 0.5.x and above includes the ability to automatically generate a TypeScript client based on your smart contract schema.

Generating a client is easy, just run the following command in your terminal.


_1
terrain contract:generateClient my_terra_dapp

The client will be generated in ./lib/clients and copied into the frontend directory.

4. Interact with the deployed contract​

The template dApp comes with several predefined helpers in lib/index.js. You may use these to start interacting with your smart contract.

  1. Start the Terrain console.

_1
terrain console

  1. In the Terrain console, you can increment the counter by running the following command.

_1
await lib.increment();

  1. You can also get the current count.

_1
await lib.getCountQuery();

  1. After incrementing once, await lib.getCountQuery() should return a count of 1.

_1
{ "count": 1 }

💡tip

Before proceeding to the next section, exit the terrain console by using "Ctrl + C".

5. Front end scaffolding​

When you scaffold a template app with Terrain, it will contain a simple front end.

  1. Open the Station Chrome extension, click the gear icon in the upper right-hand corner, and switch the network to LocalTerra.

  2. To use the front end, run the following commands.


_2
cd frontend
_2
npm start

  1. Open the Station extension and click Add a wallet. Click Recover wallet and input the following seed phrase to access the sole validator on the LocalTerra network and gain funds to get started with smart contracts:

_1
satisfy adjust timber high purchase tuition stool faith fine install that you unaware feed domain license impose boss human eager hat rent enjoy dawn

  1. With LocalTerra selected in Station and the local seed phrase imported, you can now increment and reset the counter from the front end.

Demo​

Advanced usage​

For more advanced use cases, like deploying to the testnet or mainnet, see Terrain's readme.