DOCSEARCHbyAlgolia
Submit Docs

Hiero JavaScript SDK

repository·main·Indexed 43 days ago

https://github.com/hiero-ledger/hiero-sdk-js

A library for interacting with Hiero-based networks, supporting Node.js, browser environments, and React Native/Expo. Version 2.88.0 provides features such as async client factory methods for automatic network updates, gRPC web proxy configuration for browser applications, and a dedicated service layer for React Native integration.

Tokens
28.2K
Snippets
112
Records
139
Agent score
55%

What's inside Hiero SDK

  1. Compare legacy and new transaction signing modes

    main

    When signing transactions, the behavior of signTransaction depends on the second boolean parameter:

    FeatureLegacy Mode (true)New Mode (false / default)
    Return TypeUint8Array or Uint8Array[]SignatureMap
    OrganizationRaw bytes; no node/ID mappingOrganized by node ID and transaction ID
    Chunked SupportLimitedSupports chunked transactions (e.g., FileAppend)
    StatusDeprecated (Removed in v3.0.0)Recommended

    Deprecation Timeline:

    • Current: New mode is available; legacy mode is deprecated.
    • v1.0.0: Users should have completed migration before this version.
    • v3.0.0: Legacy mode will be removed.

  2. Use KeyList instead of ThresholdKey

    main

    The ThresholdKey type has been removed. To implement threshold logic, use the KeyList class and call .setThreshold() on it.

    KeyList API:

    • of(Key[]): KeyList: Creates a list from an array of keys.
    • from(ArrayLike<Key>): KeyList: Creates a list from an array-like object.
    • threshold: number: Exposes the configured threshold.
    // Example usage of KeyList for thresholding
const keyList = KeyList.of([key1, key2, key3]);
keyList.setThreshold(2);

  3. Understand the Hiero React Native architecture

    main

    The example app follows a layered architecture to isolate the SDK from the UI:

    1. App Screens: The UI layer (Home, Transactions, Settings) built with Expo Router.
    2. Hooks & Context Layer: Uses useHiero() to provide the SDK Client instance via React Context and useNetworkConfig() for credential persistence.
    3. Service Layer: A dedicated layer (services/HieroSDKService.ts) that wraps @hiero-ledger/sdk calls. UI components should only interact with this layer, never the SDK directly.
    4. SDK Layer: The underlying @hiero-ledger/sdk (NativeClient) that performs the actual blockchain operations.

    Key Patterns:

    • Service Isolation: All SDK calls are encapsulated in the service layer.
    • Consistent Error Handling: The service layer uses an SDKResult<T> pattern, where every function returns { success: true, data } or { success: false, error }.

  5. Use async client factory methods for automatic network updates

    main
    The Hiero SDK provides async factory methods, such as forTestnetAsync(), which are preferred over synchronous methods. These methods automatically fetch and apply the latest network configuration (including node lists) from the network's address book. This approach ensures your client always uses current network state, reducing issues caused by stale node information and eliminating the need to manually call updateNetwork().

  6. Handle ED25519 and ECDSA private keys

    main

    The SDK supports both ED25519 and ECDSA private keys.

    • ED25519 is recommended for better speed and performance.
    • ECDSA is required for certain specific use cases, such as interacting with the relay.

    When manually loading a key from an environment variable, use the appropriate method based on the key type:

    • For ECDSA: Use PrivateKey.fromStringECDSA(keyString).
    • For ED25519: Use PrivateKey.fromStringED25519(keyString) (or PrivateKey.fromString() which calls the ED25519 version internally).

    In integration tests, if you are using an ECDSA key, you must update your initialization logic accordingly.

    // For ECDSA keys
const operatorKey = PrivateKey.fromStringECDSA(options.env.OPERATOR_KEY);

// For ED25519 keys (default behavior of fromString)
const operatorKey = PrivateKey.fromString(options.env.OPERATOR_KEY);

  7. Migrate Query and Transaction usage

    main

    The QueryBuilder has been renamed to Query. Additionally, TransactionBuilder and Transaction have been combined into a single Transaction class.

    Query changes:

    • QueryBuilder $\rightarrow$ Query.
    • getCost(Client) now returns Promise<Hbar> instead of Promise<number>.

    Transaction changes:

    • Transaction now handles both building and execution.
    • freeze() and freezeWith(Client) replace the old build() methods.
    • execute(Client) now returns Promise<TransactionResponse> instead of Promise<TransactionId>.
    • getTransactionHash() replaces the old hash() method.
    • setNodeAccountIds(AccountId[]) replaces setNodeId(AccountId).
    • addSignature(PublicKey, Uint8Array) allows adding manual signatures.
    • toBytes() and fromBytes(Uint8Array) are used for serialization.
    // Example of the new combined Transaction pattern
const transaction = new TransferTransaction()
  .addHbarTransfer(senderId, amount)
  .addHbarTransfer(receiverId, amount.negated())
  .freezeWith(client);

const response = await transaction.execute(client);

  8. Best practices to avoid merge conflicts

    main

    To maintain a clean history and avoid complex conflicts, follow these rules:

    • Sync regularly: Sync your branch with the main codebase frequently to avoid working on outdated versions.
    • Use Rebase, not Merge: Do not run git merge main on your feature branch; this creates messy merge commits. Always use git rebase.
    • Protect main: Never merge changes directly into your local main. Keep your local main as a clean mirror of the upstream/remote main.
    • Feature Branches Only: Do not open Pull Requests from your fork's main branch. Always use dedicated feature branches for your changes.

  9. Rebase your working branch onto main

    main

    Once your local main is up to date, you must bring your specific working branch in sync. Do not merge main into your branch; instead, use a rebase to keep the history clean and ensure commits remain eligible for review.

    Important: Always include the -S flag during the rebase operation to maintain commit signatures.

    git checkout mybranch
git rebase main -S

  10. Submit a blog post about the Hiero JavaScript SDK

    main

    To contribute a blog post regarding the Hiero JavaScript SDK, you must submit your post as a pull request to the Hiero Website Repository rather than this SDK repository.

    Follow these steps:

    1. Navigate to the Hiero Website Repository.
    2. Refer to the Hiero Website README for specific setup and creation instructions.
    3. Consult the Hiero Website Workflow Guide and the Hiero Website Blog Post Guide for detailed procedural guidance.
    4. Submit your pull request. The Hiero website community will review and publish your post upon approval.

  12. Manage Solo environment lifecycle

    main

    Use the following task commands to manage the Solo local network lifecycle. These commands control the deployment of the cluster, consensus nodes, mirror nodes, accounts, and port-forwarding services.

    # Initial provisioning + service deployment (cluster, consensus, mirror, account, port-forward)
task solo:setup

# Resume from paused state (start cluster + consensus, redeploy mirror, re-enable port-forward)
task solo:resume

# Pause environment (destroy mirror, stop consensus node(s), stop cluster, remove port-forward)
task solo:pause

# Full cleanup (remove cluster and Solo state)
task solo:teardown

# Check health and logs
task solo:status
task solo:logs