Creating and starting your first Testnet

Prerequisites

Create your first project

You need to create your own project. Follow the instructions here to do so.

Configure your credentials

Follow the instructions in the manage your credentials page to configure your keys.

Creating your Testnet configuration

Clone the Harbor start-testnet repository. Follow the instructions in the README.md to get it set-up.

Before starting your Testnet, you can optionally edit your Testnet configuration to add chains and off-chain actors.

Start your Testnet

If you’ve successfully created your Testnet config file, you should be able to run your first Testnet using the commands below in the sample-test that you cloned.

Apply configuration

Don't forget to compile your contracts first:

npx hardhat compile

After you are done modifying your configuration file, run the below command to apply it:

harbor apply <testnet-name> --config harbor.config.json

Where <testnet-name> is the same name as the Testnet you'd like to update.

You should see logs where Harbor is registering the containers in the cloud (this is reflected in the config file you provided above):

Doing preflight checks...
Creating smart contracts...
Preparing your ethereum deployment...
Building chain image... 100% |████████████████████████████████████████|                          | (0/1, 0 it/hr) [0s:0s]
⠴ Pushing images to container repository  [4s]
Constructing chain...
🌎 Testnet create/update in progress...  [1m33s]

###### 1 Chains

Chain = ⛓️ethereum
Status = ✔ RUNNING
Endpoint = 🌎 http://54.81.226.241:4000


###### 0 Off-chain actors

You can now interact with these chains and off-chain actors by the endpoints listed in the above log.

Add chain(s) (optional)

If you are in the same directory as your configuration, you can add a chain by running:

harbor configure add chain <flags>

You can add the following flags:

• artifacts-path: the path to the chain's smart contract artifacts
• chain-id the id to be used for the chain
• depends-on the dependencies for the chain
• deploy-path the path to the chain's smart contract deploy folder
• config specifies the location of the config file you want to modify
• include-paths the paths to be included while building the chain
• name the name of the chain. Accepted names are:
  • ethereum
  • arbitrum
  • polygon
  • avalanche
  • fantom
  • optimism
• tag the string that identifies the current version of the off-chain actor
  • If we are updating the actor, then we must add a new tag value and run harbor apply <testnet-name>
  • Only + - = . _ : / @ are allowed as special characters
• wallet the number of wallets
• token the symbol(s) of coins needed. Examples are:
  • ETH
  • DAI
• amount the number of tokens, respectively according to the order of the token symbols provided.

The artifacts-path, deploy-path, name, and tag are all mandatory flags.

Example

To add a simple chain:

harbor configure add chain --name polygon --artifacts-path ./artifacts/ --deploy-path ./deploy --tag v1 --config harbor.config.json

info

If you don't add the config flag, it will assume that you are updating the harbor.config.json file, if it is available. If the harbor.config.json file is not available and you don't add the flag, it'll create the file with the configuration for you. Otherwise, if the file exists, then it will just update the configuration.

This will give you a config file with the output:

{
  "chains": [
    {
      "chain": "polygon",
      "config": {
        "artifactsPath": "./artifacts",
        "deploy": { "scripts": "./deploy" }
      },
      "tag": "v1"
    }
  ]
}

Add off-chain actor(s) (optional)

To add an off-chain actor, run the command:

harbor configure add off-chain-actor <flags>

The accepted flags are:

• build-path the build path pointing towards the Dockerfile directory for our off-chain actor
• command the command to be used for the off-chain actor
• config specifies the location of the config file you want to modify
• depends-on is the array of dependencies for the off-chain actor
• docker-file the path to the Dockerfile of the off-chain actor
• env array containing environment variables to be set
• image the public image that the off-chain actor will be based off
• name the name of the actor
• ports the array of specified ports for the actor
• schedule-exp the cron schedule expression for the off-chain actor which determines the frequency with which the actor has to be invoked.
  • i.e: rate (1 minute) as a value of schedule-exp means that the off-chain actor is invoked every 1 minute
• tag the string that identifies the current version of the off-chain actor
  • If we are updating the actor, then we must add a new tag value and run harbor apply <testnet-name>
  • Only + - = . _ : / @ are allowed as special characters

The image (if public image actor) or docker-file/build-path (if locally built actor), name, ports, and tag are all mandatory flags.

Example

To add a simple off-chain actor:

harbor configure add off-chain-actor --name ipfs --image ipfs/go-ipfs:v0.4.23 --ports 5000 --tag v1 --config harbor.config.json

caution

The name of an off-chain actor cannot be more than 20 characters!

info

If you don't add the config flag, it will assume that you are updating the harbor.config.json file, if it is available. If the harbor.config.json file is not available and you don't add the flag, it'll create the file with the configuration for you. Otherwise, if the file exists, then it will just update the configuration.

This will give you the configuration:

{
  "offChainActors": [
    {
      "name": "ipfs",
      "image": "ipfs/go-ipfs:v0.4.23",
      "ports": [5000],
      "tag": "v1"
    }
  ]
}