{"id":13746517,"url":"https://github.com/hiero-ledger/hiero-sdk-js","last_synced_at":"2026-01-16T07:20:39.402Z","repository":{"id":37406110,"uuid":"198903637","full_name":"hiero-ledger/hiero-sdk-js","owner":"hiero-ledger","description":"JavaScript/TypeScript SDK for Hiero","archived":false,"fork":false,"pushed_at":"2025-05-04T19:55:42.000Z","size":40493,"stargazers_count":296,"open_issues_count":59,"forks_count":152,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-05-04T20:28:44.159Z","etag":null,"topics":["distributed-ledger-technology","hacktoberfest","hashgraph","hedera","hedera-sdk","javascript","javascript-sdk","sdk","typescript","typescript-sdk"],"latest_commit_sha":null,"homepage":"https://docs.hedera.com/guides/docs/sdks","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hiero-ledger.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-07-25T21:30:47.000Z","updated_at":"2025-05-04T19:55:44.000Z","dependencies_parsed_at":"2022-07-19T23:03:01.764Z","dependency_job_id":"f0e8c33d-8bb0-412e-8bca-8a282cce5ed8","html_url":"https://github.com/hiero-ledger/hiero-sdk-js","commit_stats":{"total_commits":1701,"total_committers":55,"mean_commits":"30.927272727272726","dds":0.7472075249853027,"last_synced_commit":"62709613fd486a719f0fbc1391508df66fa8f63e"},"previous_names":["hiero-ledger/hiero-sdk-js"],"tags_count":238,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiero-ledger%2Fhiero-sdk-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiero-ledger%2Fhiero-sdk-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiero-ledger%2Fhiero-sdk-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiero-ledger%2Fhiero-sdk-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hiero-ledger","download_url":"https://codeload.github.com/hiero-ledger/hiero-sdk-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253209259,"owners_count":21871622,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["distributed-ledger-technology","hacktoberfest","hashgraph","hedera","hedera-sdk","javascript","javascript-sdk","sdk","typescript","typescript-sdk"],"created_at":"2024-08-03T06:00:54.856Z","updated_at":"2026-01-16T07:20:39.387Z","avatar_url":"https://github.com/hiero-ledger.png","language":"JavaScript","funding_links":[],"categories":["Uncategorized","Smart Contract Platforms","**Open Source Developer Assets**"],"sub_categories":["Uncategorized","**Software Development Kits (SDKs)**"],"readme":"# Hiero JavaScript SDK\n\n[![](https://img.shields.io/discord/373889138199494658)](https://discord.com/channels/373889138199494658/616725732650909710)\n[![Docs](https://img.shields.io/badge/docs-%F0%9F%93%84-blue)](https://docs.hedera.com/hedera/getting-started/environment-set-up)\n[![JSDoc](https://img.shields.io/badge/jsdoc-%F0%9F%93%84-green)](https://hiero-ledger.github.io/hiero-sdk-js/)\n[![NPM Package](https://img.shields.io/npm/v/@hiero-ledger/sdk.svg)](https://www.npmjs.org/package/@hiero-ledger/sdk)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hiero-ledger/hiero-sdk-js/badge)](https://scorecard.dev/viewer/?uri=github.com/hiero-ledger/hiero-sdk-js)\n[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/10697/badge)](https://bestpractices.coreinfrastructure.org/projects/10697)\n[![License](https://img.shields.io/badge/license-apache2-blue.svg)](LICENSE)\n\n\u003e The JavaScript SDK for interacting with a Hiero based network\n\n\u003e [!NOTE]  \n\u003e The project has been transfered from the https://github.com/hashgraph org and therefore the namespace is at several locations still based on `hashgraph` and `hedera`.\n\u003e We are working activly on migration the namespace fully to hiero.\n\n## Install\n\n**NOTE**: v1 of the SDK is deprecated and support will be discontinued after October 2021. Please install the latest version 2.x or migrate from v1 to the latest 2.x version. You can reference the [migration documentation](./manual//MIGRATING_V1.md).\n\n```\n# with NPM\n$ npm install --save @hiero-ledger/sdk\n\n# with Yarn\n$ yarn add @hiero-ledger/sdk\n\n# with PNPM\n$ pnpm add @hiero-ledger/sdk\n```\n\n## Browser Usage\n\nThe SDK is also available as a UMD (Universal Module Definition) build, which can be loaded directly in the browser from popular CDNs:\n\n### UNPKG\n\n```html\n\u003cscript src=\"https://unpkg.com/@hiero-ledger/sdk@2.70.0/dist/umd.js\"\u003e\u003c/script\u003e\n```\n\nWhen using the UMD build in the browser, the SDK will be available as a global variable `sdk`. A minified version is also available at `dist/umd.min.js`.\n\n## Build\n\n### Prerequisites\n\n1. [Taskfile](https://taskfile.dev/) tool installation\n2. **Node.js**: It is **recommended** to use Node.js **v20 or higher** for best performance and compatibility. The package may also work with **Node.js v16**, but this version has **not been officially tested**.\n\n```\n# with npm\n$ npm install -g @go-task/cli\n\n# with homebrew\n$ brew install go-task\n```\n\n2. [pNpm](https://pnpm.io/) package manager installation\n\n```\n# with npm\n$ npm install -g pnpm\n\n# with homebrew\n$ brew install pnpm\n```\n\nAfter downloading the repo run:\n\n1. `task install`\n\n2. `task build` to build the SDK\n\n## Development\n\n### Local Development Workflow\n\nThe SDK uses `pnpm workspaces` to manage its monorepo structure with sub-packages (`@hiero-ledger/proto` and `@hiero-ledger/cryptography`). For local development and testing the SDK in other projects, use the following workflow:\n\n#### Build and Link Globally\n\nBuild the SDK and link it globally for use in other local projects:\n\n```bash\ntask build:dev\n```\n\nThis command:\n- Builds all packages (`proto`, `cryptography`, and the main SDK)\n- Creates global symlinks for all three packages\n- Allows you to use the local SDK in any other project on your machine\n\n#### Use in Another Project\n\nIn your other project, link to the globally linked SDK:\n\n```bash\ncd /path/to/your/other/project\npnpm link --global @hiero-ledger/sdk\n```\n\nNow any changes you make to the SDK and rebuild will be immediately available in your project.\n\n#### Unlink and Clean\n\nWhen you're done with local development:\n\n```bash\n# In the hiero-sdk-js repository\ntask clean\n```\n\nThis removes all global links and cleans up `node_modules`.\n\nTo unlink in your other project:\n\n```bash\n# In your other project\npnpm unlink @hiero-ledger/sdk\npnpm install\n```\n\n## React Native Support\n\nThe Hiero JavaScript SDK provides comprehensive support for React Native environments, including Expo. To ensure seamless integration, follow the guidelines based on your Expo version:\n\n✅ Hiero Javascript SDK Version 2.60 and Above\nFor projects using SDK version 2.60 and above, Expo SDK version 51+ is supported, the SDK requires the `react-native-get-random-values` package in order to work.\nTo install it, run:\n\n```bash\nnpm install react-native-get-random-values\n```\n\nAfter installation, the native dependency must be linked for the respective platforms:\n\n🔗 Linking for Native Platforms\n\n1. iOS:\n   Run the following command to install the native modules:\n\n```bash\ncd ios \u0026\u0026 pod install\n```\n\nThen, rebuild the iOS project.\n\n2. Android:\n   Rebuild the Android project to link the dependency\n\n⚠️ ✅ Hiero Javascript SDK Version 2.59 and Below\nFor projects using SDK version 2.59 and below, Expo SDK Version 49 and below is supported, keep in mind that the SDK uses some functionalities provided from ethers/ethersproject and there is an issue using parts of ethers.js in this environment. A [shims](https://www.npmjs.com/package/@ethersproject/shims) package has to be installed and imported before importing the SDK in your project.\n\n-   Useful information: [here](https://github.com/ethers-io/ethers.js/discussions/3652) and [here](https://docs.ethers.org/v5/cookbook/react-native/)\n\n```bash\nnpm install @ethersproject/shims\n```\n\nImport it before importing the SDK as shown below:\n\n```bash\nimport '@ethersproject/shims';\n\nimport {\n    Client,\n    PrivateKey\n    AccountBalance,\n} from \"@hiero-ledger/sdk\";\n...\n```\n\nThe Hiero JavaScript SDK does not currently support the following:\n\n-   React Native Bare\n\n## Usage\n\nSee [examples](./examples).\n\nEvery example can be executed using the following command from the root directory: `node examples/[name-of-example].js`.\n\n**Note:** Before running any examples, ensure you have:\n\n1. Built the SDK by running `task build` in the root directory.\n2. Installed dependencies by running `pnpm install` in the `examples` directory\n\n## Configuration\n\nFor detailed information on configuring the SDK, including environment variables and client settings, please refer to the [CONFIGURATION.md](./manual/CONFIGURATION.md) file.\n\n## Local Development Setup\n\nFor contributors and developers who want to run integration tests locally, we provide **Solo** - the official Hiero local network solution. Solo provides a production-like Kubernetes-based environment with multiple consensus nodes and mirror node services.\n\n### Quick Setup\n\n1. **Install dependencies:**\n   ```bash\n   task install\n   ```\n   \n   **Important:** This installs Solo and all project dependencies. Must be run before setup.\n\n2. **Set up Solo local network:**\n   ```bash\n   task solo:setup\n   ```\n   \n   This will automatically:\n   - Create a local Kubernetes cluster with Kind\n   - Deploy a 2-node consensus network (default: v0.69.1)\n   - Deploy mirror node services (default: v0.145.2)\n   - Create a dedicated ECDSA test account\n   - Generate a `.env` file with all necessary credentials\n\n   **Optional:** Specify custom versions or use local build:\n   ```bash\n   # Custom consensus node version\n   task solo:setup -- --consensus-node-version v0.70.0\n   \n   # Custom mirror node version\n   task solo:setup -- --mirror-node-version v0.146.0\n   \n   # Both custom versions\n   task solo:setup -- --consensus-node-version v0.70.0 --mirror-node-version v0.146.0\n   \n   # Use local build (overrides consensus-node-version)\n   task solo:setup -- --local-build-path ../hiero-consensus-node/hedera-node/data\n   ```\n\n3. **(Required for dynamic address book tests) Configure hosts:**\n   \n   Before running dynamic address book tests, add Kubernetes service names to your `/etc/hosts` file:\n   \n   ```bash\n   echo \"127.0.0.1 network-node1-svc.solo.svc.cluster.local\" | sudo tee -a /etc/hosts\n   echo \"127.0.0.1 envoy-proxy-node1-svc.solo.svc.cluster.local\" | sudo tee -a /etc/hosts\n   echo \"127.0.0.1 network-node2-svc.solo.svc.cluster.local\" | sudo tee -a /etc/hosts\n   echo \"127.0.0.1 envoy-proxy-node2-svc.solo.svc.cluster.local\" | sudo tee -a /etc/hosts\n   ```\n   \n   **Note:** This is required for dynamic address book tests to pass. Skip if you're only running other integration tests.\n\n4. **Run integration tests:**\n   ```bash\n   task test:integration\n   ```\n\n5. **Teardown when done:**\n   ```bash\n   task solo:teardown\n   ```\n\nFor detailed setup instructions, troubleshooting, and advanced usage, see the [Solo Setup Guide](./manual/SOLO_SETUP.md).\n\n### Prerequisites\n\nBefore setting up Solo, ensure you have:\n- Docker Desktop (or Docker Engine)\n- Kind (Kubernetes in Docker)\n- kubectl\n- Node.js v18+ (comes with npm/npx)\n\nSee the [Solo Setup Guide](./manual/SOLO_SETUP.md#prerequisites) for installation instructions.\n\n## Running Tests\n\n### Unit Tests\n\nUnit tests do not require a local network and can be run directly:\n\n```bash\ntask test:unit\n```\n\nOr separately for Node.js and browser:\n\n```bash\ntask test:unit:node\ntask test:unit:browser\n```\n\n### Integration Tests\n\nIntegration tests require a running local network. After setting up Solo (see above):\n\n```bash\n# Run all integration tests\ntask test:integration\n\n# Run Node.js integration tests only\ntask test:integration:node\n\n# Run browser integration tests only\ntask test:integration:browser\n\n# Run dual-mode tests\ntask test:integration:dual-mode\n```\n\n#### Running Dynamic Address Book Tests\n\nDynamic address book tests require the `/etc/hosts` configuration described in step 3 of the setup. These tests validate that the SDK can correctly handle node address changes and reconnections using Kubernetes service names.\n\n**Note:** All integration tests should pass reliably with the Solo setup. If you encounter failures:\n1. Verify Solo is running: `task solo:status`\n2. For dynamic address book test failures, ensure `/etc/hosts` is configured (see setup step 3)\n3. Check the troubleshooting section in the [Solo Setup Guide](./manual/SOLO_SETUP.md#troubleshooting)\n4. Try a fresh setup: `task solo:teardown \u0026\u0026 task solo:setup`\n\n## Contributing\n\nWhether you’re fixing bugs, enhancing features, or improving documentation, your contributions are important — let’s build something great together!\nPlease read our [contributing guide](https://github.com/hiero-ledger/.github/blob/main/CONTRIBUTING.md) to see how you can get involved.\n\n## Code of Conduct\n\nHiero uses the Linux Foundation Decentralised Trust [Code of Conduct](https://www.lfdecentralizedtrust.org/code-of-conduct).\n\n## License\n\n[Apache License 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhiero-ledger%2Fhiero-sdk-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhiero-ledger%2Fhiero-sdk-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhiero-ledger%2Fhiero-sdk-js/lists"}