Using Solo with Hiero SDKs

Overview

The Hiero SDKs let you build and test applications on the Hiero network using JavaScript / TypeScript, Java, or Go. This guide walks you through launching a local Solo network, locating its bootstrap operator account, setting up a project for your chosen SDK, and running example transactions. The Solo-side steps are identical across all three SDKs; the language-specific steps appear in tabs you can switch between.

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.

  • The shared baseline tools:

    Requirement	Version	Purpose
    Docker Desktop	Latest	Runs the Solo cluster containers
    Solo	Latest stable	Deploys and manages the local network

• Plus the SDK-specific toolchain for the language you’ll use:

  • JavaScript
  • Java
  • Go

  Requirement	Version	Purpose
  Node.js	v20 or higher	Runs your application against the SDK

  Requirement	Version	Purpose
  JDK	v21 or higher (Eclipse Temurin recommended)	Required by the Hiero Java SDK
  Gradle	v8.5 or later	Builds and runs the Java project

  Requirement	Version	Purpose
  Go	v1.25 or higher	Required by the Hiero Go SDK

Note: Solo uses Docker Desktop to spin up local Hiero consensus and mirror nodes. Ensure Docker Desktop is running before deploying the local network.

Step 1: Launch a Local Solo Network

Deploy a local Solo network by following the Solo Quickstart. Once it’s running, retrieve your deployment name with solo one-shot show deployment - the rest of this guide refers to it as <your-deployment-name>.

Step 2: Install the SDK

Install the Hiero SDK for your language.

• JavaScript
• Java
• Go

mkdir solo-js-demo && cd solo-js-demo
npm init -y
npm install @hiero-ledger/sdk

implementation("com.hedera.hashgraph:sdk:2.72.0")
implementation("io.grpc:grpc-netty-shaded:1.64.0")
implementation("org.slf4j:slf4j-nop:2.0.9")

mkdir solo-go-demo && cd solo-go-demo
go mod init solo-go-demo
go get github.com/hiero-ledger/hiero-sdk-go/v2@v2.80.0

Step 3: Locate Your Operator Credentials

solo one-shot single deploy provisions a bootstrap operator account (0.0.2) at genesis and writes its credentials to disk. Use this account as your operator - you do not need to call solo ledger account create for the examples in this guide.

• Print the operator credentials:

  cat ~/.solo/one-shot-<your-deployment-name>/accounts.json
  

• Expected output:

  {
    "systemAccounts": [
      {
        "name": "Operator",
        "accountId": "0.0.2",
        "publicKey": "302a300506032b65700321000aa8e21064c61eab86e2a9c164565b4e7a9a4146106e0a6cd03a8c395a110e92",
        "privateKey": "302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137"
      }
    ],
    "createdAccounts": [
      { "accountId": "0.0.1002", "privateKey": "0x105d050185...", "balance": "1000000 ℏ", "group": "ecdsa-alias" },
      ...
    ]
  }
  

  The systemAccounts[0] block is the operator (0.0.2) with an Ed25519 key in DER format. The createdAccounts array contains additional pre-funded ECDSA-alias accounts useful for EVM workflows.

• Save the accountId and privateKey values from systemAccounts[0] - you will configure the SDK with them in the next step.

EVM tooling note: For ethers.js, Hardhat, or Foundry, use one of the createdAccounts entries; their privateKey values are already in 0x-prefixed hex form. See Using Solo with EVM Tools for the full EVM-side workflow.

Step 4: Configure the SDK to Connect to Solo

Each SDK reads operator credentials and the network endpoint differently. Pick your language tab below.

• JavaScript
• Java
• Go

cd hiero-sdk-js

cat > .env <<EOF
# Operator account ID (systemAccounts[0].accountId from Step 3)
OPERATOR_ID="0.0.2"

# Operator private key (systemAccounts[0].privateKey from Step 3)
OPERATOR_KEY="302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137"

# Required by LocalProvider in the SDK example scripts (Step 5).
# Not used by the Client.fromConfig() snippet below, but harmless to include.
HEDERA_NETWORK="local-node"
EOF

source .env

import { Client, AccountId } from "@hiero-ledger/sdk";

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!);

cat > .env <<EOF
# Operator account ID (systemAccounts[0].accountId from Step 3)
OPERATOR_ID=0.0.2

# Operator private key (systemAccounts[0].privateKey from Step 3)
OPERATOR_KEY=302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137
EOF

set -a; source .env; set +a

import com.hedera.hashgraph.sdk.AccountId;
import com.hedera.hashgraph.sdk.AccountInfoQuery;
import com.hedera.hashgraph.sdk.Client;
import com.hedera.hashgraph.sdk.PrivateKey;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Main {
    public static void main(String[] args) throws Exception {
        String operatorId  = System.getenv("OPERATOR_ID");
        String operatorKey = System.getenv("OPERATOR_KEY");
        if (operatorId == null || operatorKey == null) {
            throw new IllegalStateException(
                    "Set OPERATOR_ID and OPERATOR_KEY env vars before running.");
        }

        Map<String, AccountId> network = new HashMap<>();
        network.put("127.0.0.1:35211", AccountId.fromString("0.0.3"));

        Client client = Client.forNetwork(network);
        client.setMirrorNetwork(List.of("127.0.0.1:38081"));
        client.setOperator(
                AccountId.fromString(operatorId),
                PrivateKey.fromString(operatorKey));

        // ... transactions and queries go here ...

        client.close();
    }
}

cat > .env <<'EOF'
# Operator account ID (systemAccounts[0].accountId from Step 3)
export OPERATOR_ID="0.0.2"

# Operator private key (systemAccounts[0].privateKey from Step 3)
export OPERATOR_KEY="302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137"

# Network name. "localhost" is the SDK's local-node preset; only used by
# ClientForName(...) - the explicit ClientForNetworkV2 path below ignores it.
export HEDERA_NETWORK="localhost"
EOF

source .env

package main

import (
    "fmt"
    "os"

    hiero "github.com/hiero-ledger/hiero-sdk-go/v2/sdk"
)

func main() {
    operatorID := os.Getenv("OPERATOR_ID")
    operatorKey := os.Getenv("OPERATOR_KEY")
    if operatorID == "" || operatorKey == "" {
        fmt.Fprintln(os.Stderr, "Set OPERATOR_ID and OPERATOR_KEY env vars before running.")
        os.Exit(1)
    }

    network := map[string]hiero.AccountID{
        "127.0.0.1:35211": {Account: 3},
    }

    client, err := hiero.ClientForNetworkV2(network)
    if err != nil {
        panic(err)
    }
    defer client.Close()

    client.SetMirrorNetwork([]string{"127.0.0.1:38081"})

    opAccID, err := hiero.AccountIDFromString(operatorID)
    if err != nil {
        panic(err)
    }
    opKey, err := hiero.PrivateKeyFromString(operatorKey)
    if err != nil {
        panic(err)
    }
    client.SetOperator(opAccID, opKey)

    // ... transactions and queries go here ...
}

Verify your configuration

Add an AccountInfoQuery for the operator and run it to confirm the client reaches Solo.

• JavaScript
• Java
• Go

const info = await new AccountInfoQuery()
  .setAccountId(AccountId.fromString(process.env.OPERATOR_ID!))
  .execute(client);

console.log("Account ID :", info.accountId.toString());
console.log("Balance    :", info.balance.toString());

var info = new AccountInfoQuery()
        .setAccountId(AccountId.fromString(operatorId))
        .execute(client);

System.out.println("Account ID : " + info.accountId);
System.out.println("Balance    : " + info.balance);

Account ID : 0.0.2
Balance    : 49989999499.9946 ℏ

info, err := hiero.NewAccountInfoQuery().
    SetAccountID(opAccID).
    Execute(client)
if err != nil {
    panic(err)
}
fmt.Printf("Account ID : %s\n", info.AccountID)
fmt.Printf("Balance    : %s\n", info.Balance)

Account ID : 0.0.2
Balance    : 4.99899994792001e+10 ℏ

The exact balance differs slightly between deployments; what matters is that an AccountInfo returns at all - that proves the gRPC pipe to the consensus node is alive and the operator credentials are valid.

Step 5: Run Transactions Against Solo

Heads up (JavaScript and Go only): The SDK example programs use the SDK’s local-node preset (LocalProvider in JS, ClientForName("localhost") in Go), which is hardcoded to 127.0.0.1:50211 (consensus gRPC) and 127.0.0.1:5600 (mirror gRPC). Solo doesn’t expose those ports by default, so the upstream example programs cannot reach the network out of the box. Either follow Make the examples reachable below, or rewrite the example to use the Client.fromConfig (JS) / ClientForNetworkV2 (Go) pattern from Step 4. The Java SDK has no local-node preset, so this caveat does not apply there.

Make the examples reachable

• JavaScript
• Java
• Go

kubectl port-forward svc/haproxy-node1-svc -n <your-deployment-name> 50211:50211 &
kubectl port-forward svc/mirror-1-grpc     -n <your-deployment-name> 5600:5600 &

kubectl port-forward svc/haproxy-node1-svc -n <your-deployment-name> 50211:50211 &
kubectl port-forward svc/mirror-1-grpc     -n <your-deployment-name> 5600:5600 &

Try a tutorial against your Solo network

Once your client is configured (Step 4), the canonical Hiero / Hedera SDK tutorials run against Solo the same way they run against testnet or mainnet - only the network endpoint changes. Pick a tutorial and follow it as written:

• Create an account
• Create a topic
• Transfer cryptocurrency
• Full tutorial index: Hiero / Hedera SDK guides

Each SDK also ships a runnable examples/ directory with dozens of additional patterns - token creation, smart contract deployment, HCS pub/sub, scheduled transactions, and more.

Verify transactions you submit in the Hiero Explorer: http://localhost:38080/localnet/dashboard.

Step 6: Tear Down the Network

When you are finished, remove the local consensus node, mirror node, block node, relay, explorer, and all data volumes:

solo one-shot single destroy \
  --deployment <your-deployment-name>

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

solo ledger file create \
  --deployment <your-deployment-name> \
  --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.

Update an Existing File

solo ledger file update \
  --deployment <your-deployment-name> \
  --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).

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

Inspect Transactions in Hiero Explorer

Open the Hiero Explorer to visually inspect submitted transactions, accounts, topics, and files. The Solo Quickstart’s Access your local network section lists the Explorer URL and port-availability behavior. Once it’s open, search by account ID, transaction ID, or topic ID to confirm that your transactions reached consensus.

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.

SDK logging

For SDK-side logs (which logger each SDK uses and how to configure it), see the upstream docs:

• JavaScript: Hiero JS SDK README
• Java: Hiero Java SDK logging guide
• Go: Hiero Go SDK README

Troubleshooting

Resources

• Solo operational workflows - Solo examples directory (node management, state backup/restore, multi-cluster setups, version upgrades, etc.).
• SDK examples and API references:
  • JavaScript - hiero-sdk-js examples · JSDoc
  • Java - hiero-sdk-java examples · Javadoc
  • Go - hiero-sdk-go examples · godoc
• EVM workflows - Using Solo with EVM Tools.
• Solo cluster internals - Accessing Solo Services.