The content of this blog post has been updated to include the latest capabilities of the Hedera Token Service.
See the latest information in: Submit Your First Consensus Message
JavaScript is one of the world’s most popular and easiest to use programming languages. This is even more true when it comes to building decentralized applications, with a surprisingly large percentage of developers choosing to use libraries like Ethereum’s web3.js, given the respective protocol.
In this post, I’ll show you how to get a Node.js environment set up for development with the Hedera Hashgraph JavaScript SDK. From there, you will create your client connection, send your first hbar transfer, and start building the future on Hedera.
Installation
For this project, you’ll want to have installed
- Node version > v10
- Download the latest version here
- NPM version > v6
- Download the latest version here
If you already have those set up, the next step is to create a node project and install the Hedera JavaScript SDK.
cd examples
mkdir hello-hedera-js
cd hello-hedera-js
npm init -y
npm i @hashgraph/sdk
You should now have a new package.json file, that includes Hedera’s JavaScript SDK as a dependency in it’s list. Additionally, if you navigate into the /node_modules folder, you should see the files comprising the JS SDK included.
Environment
Next, we’ll set up our environment by defining which Hedera network and nodes we would like to send our transactions to, as well as the account that is going to be operating this connection.
To start, you’ll likely want to use the public Hedera testnet, a free development environment that uses test hbars (or as I like to call them, testbars). If you don’t have a testnet account, you can sign up for one at the Hedera Portal. In doing so, you’ll receive a testnet Account ID and the associated public/private key pairing.
To manage our account ID, and it’s associated keys, we’re going to use a popular Node.js package called dotenv, however there are lots of alternatives out there like nvm. In order to use dotenv, you will need to install this package like you did the Hedera JavaScript SDK, with npm. Run the following command in your terminal:
npm i dotenv
To access the testnet, we’ll first create a .env file that will hold our account credentials. Within that .env file, add your information like below:
ACCOUNT_ID=0.0.123456789
PUBLIC_KEY=302a300506032b657003210013d392c9 .....
PRIVATE_KEY=302e020100300506032b657004220420 .....
Now that we’ve setup our Node.js project, SDK, and environment, we want to use those credentials to sign transactions that we send to the testnet. Let’s create an index.js file where we’ll establish a client connection.
// allow us to grab our .env variables
require("dotenv").config();
// import the 'Client' module from the Hedera JS SDK
const { Client } = require("@hashgraph/sdk");
async function main() {
// Grab our account credentials
const operatorAccount = process.env.ACCOUNT_ID;
const operatorPrivateKey = process.env.PRIVATE_KEY;
// Configure a testnet client with our Account ID & private key
const client = Client.forTestnet();
client.setOperator(operatorAccount, operatorPrivateKey);
// add the rest of your code here
// ...
}
Test your set up
Let’s test out this client to make sure it was successfully setup by sending our first hbar cryptocurrency transfer! For this, we’ll want to import the `CryptoTransferTransaction` from the Hedera JS SDK, similar to other transactions, queries, or modules. You can add this as the next imported module after the Client, at the top of your file.
// ...
const { Client, CryptoTransferTransaction } = require("@hashgraph/sdk");
// ...
Then we’ll create and use that `.CryptoTransferTransaction()` within the ‘.main()’ function we previously created. A lot of the details for this transaction are handled by the SDK, like managing transaction fees, but we’ll still have to specify a few details. In this case, we’ll send 1 hbar from our account, to account 0.0.3, which is actually one of the testnet nodes. But this could be any account on the public testnet! Maybe you could even try sending some to mine (0.0.142293)?
/* imports, client config, etc. above ... */
const transactionId = await new CryptoTransferTransaction()
.addSender(operatorAccount, 1)
.addRecipient("0.0.3", 1)
.setTransactionMemo("Hello future!")
.execute(client);
const receipt = transactionId.getReceipt(client);
console.log(receipt);
} /* Close of the main() function */
main(); // make sure to call your main function
There’s a fair amount of other things going on in this transaction that the SDK doesn’t manage or populate by default, so let me explain.
- .setTransactionMemo() allows us to add messages into our transfers.
- .execute() will generate and sign the new transaction, and additionally submit it to a node that is specified in your client connection. If you didn’t specify a specific node for this transaction to be submitted to, the SDKs will pick one from the address book at random.
- .getReceipt() will ask the network if there’s a receipt for this specific transaction ID (which was generated after the transaction executed). Receipts and records, by default, only exist on the network for ~4 minutes. After this duration, they will be removed from the network, and persisted to any Mirror Nodes that are listening.
The full JS SDK reference documentation can be found here.
If you have successfully followed along, you should be able to run `node index.js` in your terminal. If your hbar transfer was successful, receive a receipt that looks similar to this:
TransactionReceipt {
status: Status { code: 22 },
_accountId: null,
_fileId: null,
_contractId: null,
_topicId: null,
_exchangeRateSet:
{ currentRate:
{ hbarEquiv: 30000,
centEquiv: 150000,
expirationTime: 1970-01-19T07:27:39.600Z },
nextRate:
{ hbarEquiv: 30000,
centEquiv: 150000,
expirationTime: 1970-01-19T07:27:39.600Z } },
_topicSequenceNubmer: 0,
_topicRunningHash: Uint8Array [] }
While here, you can also check to see if your transaction was successful in one of the available Hedera Testnet explorers, by searching for your Operator Account ID. Here’s an example from when I did it.
And finally, to recap, here’s what the entire `index.js` file should look like:
/* allow us to use our .env variables */
require("dotenv").config();
/* import the Hedera JavaScript SDK */
const { Client, CryptoTransferTransaction } = require("@hashgraph/sdk");
/* create a new asynchronous function */
async function main() {
/* grab our testnet credentials from our .env file */
const operatorAccount = process.env.ACCOUNT_ID;
const operatorPrivateKey = process.env.PRIVATE_KEY;
/* configure our testnet client */
const client = Client.forTestnet();
client.setOperator(operatorAccount, operatorPrivateKey);
/* send our first hbar transfer! */
const transactionId = await new CryptoTransferTransaction()
.addSender(operatorAccount, 1)
.addRecipient("0.0.3", 1)
.setTransactionMemo("Hello future!")
.execute(client);
/* get the receipt of this transfer */
const receipt = await transactionId.getReceipt(client);
console.log(receipt);
}
/* call our async function */
main();
With that you’ve successfully set up your Node.js environment for Hedera development, and can start moving onto using other Hedera network services. In our next part, we’ll cover creating your first Hedera Consensus Service Topic and sending HCS messages!
Have any issues? Please let us know on Discord.
