A great way to learn to test and build on the Hedera network is setting up your own Hedera local node. This article is focused on how to set up your own local network and how to test that it is operating correctly.
The local network consists of one mirror node and one consensus node and can be started using Docker or using the CLI tool.
You can find the official GitHub repository for Hedera Local Node here.
What Can I Accomplish With My Own Local Network?
- Create and submit transactions to your consensus node
- Query transactions on your consensus node
- Interact with your local mirror node through Rest API’s
- Complete Application Testing/Debugging
Why Should I Set Up My Own Local Network?
Application testing and debugging should be done on your own local network. A benefit of having your own local network is ensuring your work isn’t being interrupted by others throttling the network while conducting their own testing/debugging. It is also a great way to start to learn how to build on the Hedera network.
If I Set Up My Own Local Network, When Should I Use TestNet?
You should use testnet when your application is almost ready for production and are thinking of transitioning to mainnet soon. Testnet nodes run the same code as the HEdera minnet nodes.
How to Set Up My Local Network
Open your terminal and clone the hedera-local-node repo.
git clone https:://github.com/hashgraph/hedera-local-node.git
How to Start Your Local Network Using Docker
Requirements:
- Node.js >= v16.x
- Npm >= v8.5
- Docker >= v20.10.x
- Docker Compose >= v1.29.2
Note: If you are using a mac with a Silicon Chip and need to install Docker please go here.
Start up Your Local Network
CD into the hedera-local-node directory.
cd hedera-local-node
Start the network up by starting the docker containers using docker compose.
docker-compose up -d
Great! Once you’ve got the containers running you will see the following output.
[+] Running 11/11
[+] Running 13/14storage Created 0.0s
[+] Running 12/14storage Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 13/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 13/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 13/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 13/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 12/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 14/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 14/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 14/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 14/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 14/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
[+] Running 15/15-node Created 0.0s
⠿ Network cloud-storage Created 0.0s
⠿ Network mirror-node Created 0.0s
⠿ Network network-node-bridge Created 0.0s
⠿ Volume "mirror-node-postgres" Created 0.0s
⠿ Volume "minio-data" Created 0.0s
⠿ Container mirror-node-db Started 1.0s
⠿ Container minio Started 1.0s
⠿ Container haveged Started 0.7s
⠿ Container account-balances-uploader Started 1.6s
⠿ Container record-streams-uploader Started 1.4s
⠿ Container mirror-node-importer Started 1.6s
⠿ Container network-node Started 2.1s
⠿ Container mirror-node-web3 Started 2.2s
⠿ Container mirror-node-rest Started 2.2s
⠿ Container mirror-node-grpc Started 2.5s
You can list which containers are currently running by typing the following command.
docker container ls
// Output
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
876da819ad8a gcr.io/mirrornode/hedera-mirror-grpc:0.57.2 "java org.springfram…" About a minute ago Up About a minute (healthy) 0.0.0.0:5600->5600/tcp mirror-node-grpc
50cdd0b4f830 gcr.io/hedera-registry/main-network-node:0.26.2 "/opt/hgcapp/service…" About a minute ago Up About a minute 50111/tcp, 0.0.0.0:50211-50212->50211-50212/tcp network-node
0be902a7ba69 gcr.io/mirrornode/hedera-mirror-rest:0.57.2 "node server.js" About a minute ago Up About a minute (healthy) 0.0.0.0:5551->5551/tcp mirror-node-rest
2e2f501712d1 gcr.io/mirrornode/hedera-mirror-web3:0.57.2 "java org.springfram…" About a minute ago Up About a minute (healthy) 0.0.0.0:8545->8545/tcp mirror-node-web3
03e5236690cc gcr.io/mirrornode/hedera-mirror-importer:0.57.2 "java org.springfram…" About a minute ago Up About a minute (healthy) mirror-node-importer
8f481bfce674 gcr.io/hedera-registry/uploader-mirror:0.5.0 "/usr/bin/env python…" About a minute ago Up About a minute record-streams-uploader
d45bae1bb9da gcr.io/hedera-registry/uploader-mirror:0.5.0 "/usr/bin/env python…" About a minute ago Up About a minute account-balances-uploader
5efcbd44018e postgres:13.5-alpine "docker-entrypoint.s…" About a minute ago Up About a minute 5432/tcp mirror-node-db
0ccd6696972c minio/minio "sh -c 'mkdir -p /da…" About a minute ago Up About a minute 0.0.0.0:9000-9001->9000-9001/tcp minio
c04dae19a4e5 gcr.io/hedera-registry/network-node-haveged:0.26.2 "/usr/bin/env havege…" About a minute ago Up About a minute haveged
Setting Up Your Client
In order to start interacting with your local network you will need to set up your client by configuring it to point to your local network. You can do this by using any project of your choice and ensuring you have your language specific Hedera SDK as a dependency and imported into your project. If you need a quick refresher you can reference the environment set-up instructions.
Instructions to completing your client setup can be found here.
Testing your client with your local network
Once you have configured your client to point to your local network by completing the instructions above you are going to create a transaction.
In your client project open a terminal and execute your client code. In this example we will be executing a javascript file.
node my-client-file.js
When it is done executing you will see the following output.
{
receipt: TransactionReceipt {
status: Status { _code: 22 },
accountId: AccountId {
shard: [Long],
realm: [Long],
num: [Long],
aliasKey: null,
aliasEvmAddress: null,
_checksum: null
},
fileId: null,
contractId: null,
topicId: null,
tokenId: null,
scheduleId: null,
exchangeRate: ExchangeRate {
hbars: 1,
cents: 12,
expirationTime: 1963-11-25T17:31:44.000Z,
exchangeRateInCents: 12
},
topicSequenceNumber: Long { low: 0, high: 0, unsigned: false },
topicRunningHash: Uint8Array(0) [],
totalSupply: Long { low: 0, high: 0, unsigned: false },
scheduledTransactionId: null,
serials: [],
duplicates: [],
children: []
}
}
AccountId {
shard: Long { low: 0, high: 0, unsigned: false },
realm: Long { low: 0, high: 0, unsigned: false },
num: Long { low: 1002, high: 0, unsigned: false },
aliasKey: null,
aliasEvmAddress: null,
_checksum: null
}
You can view the transaction you just performed by querying your local mirror node at http://localhost:551/api/v1/transactions.
{"transactions":[{"bytes":null,"charged_tx_fee":0,"consensus_timestamp":"1655270647.389977590","entity_id":"0.0.1001","max_fee":"200000000","memo_base64":"","name":"CRYPTOCREATEACCOUNT","node":"0.0.3","nonce":0,"parent_consensus_timestamp":null,"result":"SUCCESS","scheduled":false,"transaction_hash":"ITm+7STfl6TBfFrURcGRWiHSRLmleQ3nPq2W+d2SoaT076uMuIykCju/gSxyucDO","transaction_id":"0.0.2-1655270639-102160281","transfers":[{"account":"0.0.2","amount":-100000000,"is_approval":false},{"account":"0.0.1001","amount":100000000,"is_approval":false}],"valid_duration_seconds":"120","valid_start_timestamp":"1655270639.102160281"},{"bytes":null,"charged_tx_fee":0,"consensus_timestamp":"1655270647.389977589","entity_id":"0.0.800","max_fee":"0","memo_base64":"","name":"CRYPTOCREATEACCOUNT","node":null,"nonce":1,"parent_consensus_timestamp":null,"result":"SUCCESS","scheduled":false,"transaction_hash":"ebYw3lJl2cQHjdpk6pIV9xB5hPN6MoyBNXCtR6Mtm0y8QQC5IntcumPr1rmP5l05","transaction_id":"0.0.2-1655270639-102160281","transfers":[],"valid_duration_seconds":null,"valid_start_timestamp":"1655270639.102160281"},{"bytes":null,"charged_tx_fee":0,"consensus_timestamp":"1655270647.389977588","entity_id":"0.0.801","max_fee":"0","memo_base64":"","name":"CRYPTOCREATEACCOUNT","node":null,"nonce":2,"parent_consensus_timestamp":null,"result":"SUCCESS","scheduled":false,"transaction_hash":"vvU3q2drpDzX88bUT5QIlSQp0oPBuD+bHjRTqqyCLaiTnRyAoo6hwcfmek/Pm5Es","transaction_id":"0.0.2-1655270639-102160281","transfers":[],"valid_duration_seconds":null,"valid_start_timestamp":"1655270639.102160281"}],"links":{"next":null}}%
You can use an online json formatting tool to make the output more readable.
{
"bytes":null,
"charged_tx_fee":0,
"consensus_timestamp":"1655270647.389977590",
"entity_id":"0.0.1001",
"max_fee":"200000000",
"memo_base64":"",
"name":"CRYPTOCREATEACCOUNT",
"node":"0.0.3",
"nonce":0,
"parent_consensus_timestamp":null,
"result":"SUCCESS",
"scheduled":false,
"transaction_hash":"ITm+7STfl6TBfFrURcGRWiHSRLmleQ3nPq2W+d2SoaT076uMuIykCju/gSxyucDO",
"transaction_id":"0.0.2-1655270639-102160281",
"transfers":[
{
"account":"0.0.2",
"amount":-100000000,
"is_approval":false
},
{
"account":"0.0.1001",
"amount":100000000,
"is_approval":false
}
],
"valid_duration_seconds":"120",
"valid_start_timestamp":"1655270639.102160281"
},
{
"bytes":null,
"charged_tx_fee":0,
"consensus_timestamp":"1655270647.389977589",
"entity_id":"0.0.800",
"max_fee":"0",
"memo_base64":"",
"name":"CRYPTOCREATEACCOUNT",
"node":null,
"nonce":1,
"parent_consensus_timestamp":null,
"result":"SUCCESS",
"scheduled":false,
"transaction_hash":"ebYw3lJl2cQHjdpk6pIV9xB5hPN6MoyBNXCtR6Mtm0y8QQC5IntcumPr1rmP5l05",
"transaction_id":"0.0.2-1655270639-102160281",
"transfers":[
],
"valid_duration_seconds":null,
"valid_start_timestamp":"1655270639.102160281"
},
{
"bytes":null,
"charged_tx_fee":0,
"consensus_timestamp":"1655270647.389977588",
"entity_id":"0.0.801",
"max_fee":"0",
"memo_base64":"",
"name":"CRYPTOCREATEACCOUNT",
"node":null,
"nonce":2,
"parent_consensus_timestamp":null,
"result":"SUCCESS",
"scheduled":false,
"transaction_hash":"vvU3q2drpDzX88bUT5QIlSQp0oPBuD+bHjRTqqyCLaiTnRyAoo6hwcfmek/Pm5Es",
"transaction_id":"0.0.2-1655270639-102160281",
"transfers":[
],
"valid_duration_seconds":null,
"valid_start_timestamp":"1655270639.102160281"
}
How to Stop Your Local Network
It is important to stop and remove containers, volumes and clean up any generated files. If you would like to keep any files generated inside your working directory please save them before executing the below command.
docker-compose down -v; git clean -xfd; git reset --hard
How To Start Up Your Network Using The CLI Tool
The hedera-local-node repo has a package that defines basic cli commands to start your network and also interact with it.
// cd into directory
cd hedera-local-node
Install the hedera-local dependency.
npm install --save-dev @hashgraph/hedera-local
How to use hedera-local
After installing the package you can find available commands by typing the following command.
npx hedera-local
// Output
Local Hedera Package - Runs consensus and mirror nodes on localhost:
- consensus node url - 127.0.0.1:50211
- node id - 0.0.3
- mirror node url - http://127.0.0.1:5551
Available commands:
start - Starts the local hedera network.
stop - Stops the local hedera network and delete all the existing data.
restart - Restart the local hedera network.
generate-accounts - Generates N accounts, default 10.
Start up Your Local Network
npx hedera-local start
When using the CLI tool and starting up the project it goes ahead and creates the docker containers, starts a pinger and begins generating accounts.
The default amount of accounts to create is 10 if not specified and they use the predefined private keys. All accounts after that are with random generated private keys.
//Output
Starting the docker images...
Starting the pinger...
Generating accounts...
---------- Accounts list:
0.0.1001 - 0x7f109a9e3b0d8ecfba9cc23a3614433ce0fa7ddcc80f2a8f10b222179a5a80d6 - 100000 ℏ
0.0.1002 - 0x6ec1f2e7d126a74a1d2ff9e1c5d90b92378c725e506651ff8bb8616a5c724628 - 100000 ℏ
0.0.1003 - 0xb4d7f7e82f61d81c95985771b8abf518f9328d019c36849d4214b5f995d13814 - 100000 ℏ
0.0.1004 - 0x941536648ac10d5734973e94df413c17809d6cc5e24cd11e947e685acfbd12ae - 100000 ℏ
0.0.1005 - 0x5829cf333ef66b6bdd34950f096cb24e06ef041c5f63e577b4f3362309125863 - 100000 ℏ
0.0.1006 - 0x8fc4bffe2b40b2b7db7fd937736c4575a0925511d7a0a2dfc3274e8c17b41d20 - 100000 ℏ
0.0.1007 - 0xb6c10e2baaeba1fa4a8b73644db4f28f4bf0912cceb6e8959f73bb423c33bd84 - 100000 ℏ
0.0.1008 - 0xfe8875acb38f684b2025d5472445b8e4745705a9e7adc9b0485a05df790df700 - 100000 ℏ
0.0.1009 - 0xbdc6e0a69f2921a78e9af930111334a41d3fab44653c8de0775572c526feea2d - 100000 ℏ
0.0.1010 - 0x3e215c3d2a59626a669ed04ec1700f36c05c9b216e592f58bbfd3d8aa6ea25f9 - 100000 ℏ
---------- Total: 10
npx hedera-local start --acounts=2
//Output
Starting the docker images...
Starting the pinger...
Generating accounts...
---------- Accounts list:
0.0.1001 - 0x7f109a9e3b0d8ecfba9cc23a3614433ce0fa7ddcc80f2a8f10b222179a5a80d6 - 100000 ℏ
0.0.1002 - 0x6ec1f2e7d126a74a1d2ff9e1c5d90b92378c725e506651ff8bb8616a5c724628 - 100000 ℏ
---------- Total: 2
You can interact with your local network through the CLI commands and generate accounts with the following command.
npx hedera-local generate-accounts 2
//Output
---------- Accounts list:
0.0.1003 - 0xfbb758df3a6aab2e0eac205986eebd53b72fa56f659ed9b733772797834b0099 - 100000 ℏ
0.0.1004 - 0x623a5076487903920f3037d5b733d7cf60523cfb726c9aece51df30a0235854e - 100000 ℏ
---------- Total: 2
Once your transactions have been submitted you can query your local mirror node and view your transaction at http://localhost:551/api/v1/transactions.
How to Stop My Local Network
npx hedera-local stop
// Output
Stopping the pinger...
Stopping the docker images...
Cleaning the volumes and temp files...
This concludes learning how to set up your local network and either start it using docker and interact with it using your own client or starting and interacting with your network using the CLI tools.
For any feedback on this article or future articles you would like to see, let us know via the Hedera Discord Server.
