Using Solo with Hiero JavaScript SDK

Overview

The Hiero JavaScript SDK lets you build and test applications on the Hiero network using JavaScript or TypeScript. This guide walks you through launching a local Solo network, creating a funded test account, connecting the SDK, and running example scripts to submit your first transaction.

Prerequisites

Before proceeding, ensure you have completed the following:

• System Readiness:

  • Your local environment meets all hardware and software requirements, including Docker, kubectl, and Solo.

  • You will need the following tools installed:

    Requirement	Version	Purpose
    Docker Desktop	Latest	Runs the Solo cluster containers
    Solo	Latest	Deploys and manages the local network
    Node.js	v18 or higher	Runs the SDK examples
    Taskfile	Latest	Runs convenience scripts in the Solo repo

Note: Solo uses Docker Desktop to spin up local Hiero consensus and mirror nodes. Ensure Docker Desktop is running before executing any task commands.

Step 1: Launch a Local Solo Network

Start the network with a single consensus node, mirror node, and Hiero Explorer:

solo one-shot single deploy

This command:

• Creates a local Kind Kubernetes cluster.
• Deploys a local Hiero consensus node.
• Deploys a mirror node for transaction history queries and the Hiero Explorer.

Once complete, the Hiero Explorer is available at: http://localhost:38080/localnet/dashboard (Solo 0.63+) or http://localhost:8080/localnet/dashboard (Solo 0.62 and earlier). If the port is in use, Solo picks the next available one — see Port availability to find the active assignment.

Note for contributors: If you are working from a cloned Solo repository, you can use task default-with-mirror from the scripts/ directory as an alternative.

Step 2: Install the Hiero JavaScript SDK

• Clone the Hiero JavaScript SDK repository and install its dependencies:

  git clone https://github.com/hiero-ledger/hiero-sdk-js.git
  cd hiero-sdk-js
  npm install
  

• The SDK provides classes for building and submitting transactions (e.g., AccountCreateTransaction, TopicCreateTransaction) and for reading receipts and query responses from the network.

Step 3: Create a Test Account

• With your Solo network running, create a funded operator account with 100 HBAR that your scripts will use to sign and pay for transactions.

  solo ledger account create \
    --deployment solo-deployment \
    --hbar-amount 100
  

  Note for contributors: If you are working from a cloned Solo repository, you can run npm run solo-test -- ledger account create ... as an alternative.

• Example output:

  *** new account created ***
  -------------------------------------------------------------------------------
  {
  "accountId": "0.0.1007",
  "publicKey": "302a300506032b65700321001d8978e647aca1195c54a4d3d5dc469b95666de14e9b6edde8ed337917b96013",
  "balance": 100
  }
  

Note the accountId value (0.0.1007 in this example). You will use it in the next step.

Retrieve the Private Key

• To sign transactions you need the account’s private key. Retrieve it with:

  solo ledger account info \
    --account-id 0.0.1007 \
    --deployment solo-deployment \
    --private-key
  

• Expected output:

  {
    "accountId": "0.0.1007",
    "privateKey": "302e020100300506032b657004220420411a561013bceabb8cb83e3dc5558d052b9bd6a8977b5a7348bf9653034a29d7",
    "privateKeyRaw": "411a561013bceabb8cb83e3dc5558d052b9bd6a8977b5a7348bf9653034a29d7",
    "publicKey": "302a300506032b65700321001d8978e647aca1195c54a4d3d5dc469b95666de14e9b6edde8ed337917b96013",
    "balance": 100
  }
  

• Save the accountId and privateKey values - you will configure the SDK with them in the next step.

Step 4: Configure the SDK to Connect to Solo

• The Hiero JavaScript SDK uses environment variables to authenticate the operator account. Create a .env file at the root of the hiero-sdk-js directory:

  # Navigate to the SDK root
  cd hiero-sdk-js
  
  # Create the environment file
  cat > .env <<EOF
  
  # Operator account ID (accountId from Step 3)
  OPERATOR_ID="0.0.1007"
  
  # Operator private key (not publicKey) from Step 3
  OPERATOR_KEY="302e020100300506032b657004220420411a561013bceabb8cb83e3dc5558d052b9bd6a8977b5a7348bf9653034a29d7"
  EOF
  
  # Load the variables into your current shell session
  source .env
  

  Important: OPERATOR_KEY must be set to the privateKey value, not the publicKey. The private key is the longer DER-encoded string beginning with 302e....

• Configure the client with the Solo 0.63+ port-forwards using Client.fromConfig(). The SDK’s built-in Client.forLocalNode() preset is hardcoded to localhost:50211, which does not match Solo 0.63+ defaults (localhost:35211 for consensus gRPC, localhost:38081 for the mirror node ingress). Use the explicit network map shown below instead:

  import { Client, AccountId } from "@hiero-ledger/sdk";
  
  // Solo 0.63+ default port-forwards.
  // For Solo 0.62 and earlier, use 127.0.0.1:50211 and 127.0.0.1:8081.
  const network = { "127.0.0.1:35211": AccountId.fromString("0.0.3") };
  const mirrorNetwork = "127.0.0.1:38081";
  
  const client = Client.fromConfig({
    network,
    mirrorNetwork,
    // Required: the SDK's address-book refresh otherwise pulls in the
    // hardcoded 50211/50212 ports, which Solo 0.63+ does not expose.
    scheduleNetworkUpdate: false,
  });
  client.setOperator(process.env.OPERATOR_ID!, process.env.OPERATOR_KEY!);
  

  Note: If a port is already in use on your machine, Solo picks the next available port — see Port availability to find the active assignment and substitute it above.

Step 5: Submit Your First Transaction

Heads up: The example scripts shipped in hiero-sdk-js (e.g. examples/create-account.js) call Client.forLocalNode(), which is hardcoded to localhost:50211. To run them against Solo 0.63+, either edit the example to use the Client.fromConfig({ network, mirrorNetwork, scheduleNetworkUpdate: false }) pattern from Step 4, or expose the legacy port manually before running the script:

kubectl port-forward svc/haproxy-node1-svc -n solo-deployment 50211:50211 &

Example 1: Create an Account (AccountCreateTransaction)

• This example uses AccountCreateTransaction to create a new account on your local Solo network, waits for consensus, and prints the resulting receipt.

  node examples/create-account.js
  

• Expected output:

  private key = 302e020100300506032b6570042204208a3c1093c4df779c4aa980d20731899e0b509c7a55733beac41857a9dd3f1193
  public key = 302a300506032b6570032100c55adafae7e85608ea893d0e2c77e2dae3df90ba8ee7af2f16a023ba2258c143
  account id = 0.0.1009
  

What happened:

1. The SDK built an AccountCreateTransaction signed by your operator key.
2. The transaction was submitted to the Solo consensus node.
3. The SDK polled for the transaction receipt until consensus was reached.
4. The receipt confirmed the new account ID (0.0.1009).

Example 2: Create a Topic (TopicCreateTransaction)

• The Hiero Consensus Service (HCS) lets you create topics and publish messages to them. Run the topic creation example:

  node examples/create-topic.js
  

• Expected output:

  topic id = 0.0.1008
  topic sequence number = 1
  

What happened:

1. The SDK submitted a TopicCreateTransaction.
2. After consensus, the receipt returned a new topic ID (0.0.1008).
3. A test message was published and its sequence number confirmed.

Verify both transactions in the Hiero Explorer: http://localhost:38080/localnet/dashboard (Solo 0.63+) or http://localhost:8080/localnet/dashboard (Solo 0.62 and earlier).

Step 6: Tear Down the Network

When you are finished, stop and remove all Solo containers:

# Run from the solo/scripts directory
cd solo/scripts
task clean

This removes the local consensus node, mirror node, and all associated data volumes.

Read a Transaction Receipt

• Every transaction submitted via the Hiero JavaScript SDK returns a TransactionReceipt after reaching consensus. A receipt includes:

  Field	Description
  status	SUCCESS if consensus was reached, otherwise an error code
  accountId	Set when an account was created
  topicId	Set when a topic was created
  fileId	Set when a file was created
  topicSequenceNumber	Sequence number of an HCS message

• In your own TypeScript/JavaScript code, the pattern looks like this:

  import {
    AccountCreateTransaction,
    AccountId,
    Client,
    Hbar,
    PrivateKey,
  } from "@hiero-ledger/sdk";
  
  // Configure the client for Solo 0.63+ port-forwards.
  // For Solo 0.62 and earlier, use 127.0.0.1:50211 and 127.0.0.1:8081.
  const client = Client.fromConfig({
    network: { "127.0.0.1:35211": AccountId.fromString("0.0.3") },
    mirrorNetwork: "127.0.0.1:38081",
    scheduleNetworkUpdate: false,
  });
  client.setOperator(
    process.env.OPERATOR_ID!,
    process.env.OPERATOR_KEY!
  );
  
  // Build and submit the transaction
  const newKey = PrivateKey.generateED25519();
  const response = await new AccountCreateTransaction()
    .setKey(newKey.publicKey)
    .setInitialBalance(new Hbar(10))
    .execute(client);
  
  // Wait for consensus and read the receipt
  const receipt = await response.getReceipt(client);
  
  console.log(`Transaction status : ${receipt.status}`);
  console.log(`New account ID     : ${receipt.accountId}`);
  

  Tip: If receipt.status is not SUCCESS, the SDK throws a ReceiptStatusError with the error code. Common causes on a fresh Solo network are insufficient HBAR balance or a misconfigured operator key.

Optional: Manage Files on the Network

Solo provides CLI commands to create and update files stored on the Hiero File Service.

Create a New File

npm run solo-test -- ledger file create \
  --deployment solo-deployment \
  --file-path ./config.json

This command:

• Creates a new file on the network and returns a system-assigned file ID.
• Automatically splits files larger than 4 KB into chunks using FileAppendTransaction.
• Verifies that the uploaded content matches the local file.

Example output:

✓ Initialize configuration
  File: config.json
  Size: 2048 bytes

✓ Load node client and treasury keys

✓ Create file on Hiero network
  ✓ Create new file
    Creating file with 2048 bytes...
    ✓ File created with ID: 0.0.1234

✓ Verify uploaded file
  Querying file contents to verify upload...
  Expected size: 2048 bytes
  Retrieved size: 2048 bytes
  ✓ File verification successful
  ✓ Size: 2048 bytes
  ✓ Content matches uploaded file

✅ File created successfully!
📄 File ID: 0.0.1234

Update an existing file

npm run solo-test -- ledger file update \
  --deployment solo-deployment \
  --file-id 0.0.1234 \
  --file-path ./updated-config.json

This command:

• Verifies the file exists on the network (errors if not found).
• Replaces the file content and re-verifies the upload.
• Automatically handles chunking for large files (>4 KB).

Example output:

✓ Initialize configuration
  File: updated-config.json
  Size: 3072 bytes
  File ID: 0.0.1234

✓ Load node client and treasury keys

✓ Check if file exists
  File 0.0.1234 exists. Proceeding with update.
  Current size: 2048 bytes
  Keys: 1

✓ Update file on Hiero network
  ✓ Update existing file
    Updating file with 3072 bytes...
    ✓ File updated successfully

✓ Verify uploaded file
  Querying file contents to verify upload...
  Expected size: 3072 bytes
  Retrieved size: 3072 bytes
  ✓ File verification successful
  ✓ Size: 3072 bytes
  ✓ Content matches uploaded file

✅ File updated successfully!

Note: For files larger than 4 KB, both commands split content into 4 KB chunks and display per-chunk progress during the append phase.

✓ Create file on Hiero network
  ✓ Create new file
    Creating file with first 4096 bytes (multi-part create)...
    ✓ File created with ID: 0.0.1234
  ✓ Append remaining file content (chunk 1/3)
    Appending chunk 1/3 (4096 bytes, 8192 bytes remaining)...
  ✓ Append remaining file content (chunk 2/3)
    Appending chunk 2/3 (4096 bytes, 4096 bytes remaining)...
  ✓ Append remaining file content (chunk 3/3)
    Appending chunk 3/3 (4096 bytes, 0 bytes remaining)...
  ✓ Append remaining file content (3 chunks completed)
    ✓ Appended 3 chunks successfully

Inspect Transactions in Hiero Explorer

While your Solo network is running, open the Hiero Explorer to visually inspect submitted transactions, accounts, topics, and files:

http://localhost:38080/localnet/dashboard

Note: If you are using Solo 0.62 or earlier, the Explorer is at http://localhost:8080/localnet/dashboard. If the port is in use, Solo picks the next available one — see Port availability to find the active assignment.

You can search by account ID, transaction ID, or topic ID to confirm that your transactions reached consensus and view their receipts.

Retrieving Logs

Solo writes logs to ~/.solo/logs/:

The Solo log is useful for debugging connectivity issues between the SDK and your local Solo network.

The Hiero JavaScript SDK uses Pino for logging and writes to the console by default. It does not write to a file on its own. To configure file-based SDK logging, see the Pino documentation.

Troubleshooting