{"id":28165632,"url":"https://github.com/fireblocks/hbar-fireblocks-sdk","last_synced_at":"2025-05-15T12:11:55.617Z","repository":{"id":279078895,"uuid":"859715434","full_name":"fireblocks/hbar-fireblocks-sdk","owner":"fireblocks","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-09T08:19:45.000Z","size":11653,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-23T16:36:39.049Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fireblocks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-19T06:46:52.000Z","updated_at":"2024-12-09T08:21:29.000Z","dependencies_parsed_at":"2025-02-23T16:48:13.474Z","dependency_job_id":null,"html_url":"https://github.com/fireblocks/hbar-fireblocks-sdk","commit_stats":null,"previous_names":["fireblocks/hbar-fireblocks-sdk"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireblocks%2Fhbar-fireblocks-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireblocks%2Fhbar-fireblocks-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireblocks%2Fhbar-fireblocks-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireblocks%2Fhbar-fireblocks-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fireblocks","download_url":"https://codeload.github.com/fireblocks/hbar-fireblocks-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254337509,"owners_count":22054255,"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":[],"created_at":"2025-05-15T12:11:55.529Z","updated_at":"2025-05-15T12:11:55.596Z","avatar_url":"https://github.com/fireblocks.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fireblocks Hedera SDK Client and Signer\n\nThis repo contains an implementation of an hedera Client that is used for signing operations with the Fireblocks SDK.\nThe implementation in this repo follows [HIP-338](https://hips.hedera.com/hip/hip-338).\u003cbr/\u003e\n**The implementation is a wrapper for Raw Signing**, handling all the raw signing calls required to abstract it and make for an easy and seamless integration with Fireblocks and the Hedera SDK\n\n## Requirements\n\nTo use this Client you will need the following:\n\n1. Raw signing enabled on the workspace\n2. A Fireblocks API User\n3. A vault account with the corresponding HBAR or HBAR_TEST wallet\n4. Some funds in your relevant wallet\n\n## How does it work\n\nThis SDK provides two functionalities depending on what is needed;\n\n1. Client - an HIP-338 client which extends Hedera's standard client (Node client by default) and provides signing functionality so it can be easily integrated into existing code\n2. Signer - an HIP-338 signer that can be used in case of multi-signature operations\n\nThe Client we provide simply extends Hedera's client. Once a signature is required, the Fireblocks SDK will request a signature and provide the result to the caller.\u003cbr/\u003e\nBy default Hedera uses several nodes, each node requires a custom payload (with relevant node ID information) to be signed, and as a result we offer a caching signing mechanism, please see the signature caching below.\n\n## How to use the SDK\n\nThe primary focus of the SDK is to provide an easily implmentable approach to use the Fireblocks SDK with Hedera's SDK.\nWe take into account two potential use-cases:\n\n### Node count\n\nHedera SDK offers the ability to send the transaction to multiple nodes in a sequential order in case one does not accept. As such each transaction to a node has their own unique node id embeded in the transaction. This means that each transaction to a node needs to be different and requires its own signature.\n\nSet the maximum number of nodes to one; this will make it so that when sending a transaction only a single node (determined by the Hedera's SDK's internal mechanisms), to do this use the `maxNumberOfPayloadsPerTransaction` parameter as part of your `clientConfig`:\n\n```javascript\nconst clientConfig = {\n  apiKey: \"01234567-89ab-cdef-0123-456789abcdef\",\n  privateKey: \"/path/to/private/key\",\n  vaultAccountId: X,\n  testnet: true,\n  apiEndpoint: Y,\n  maxNumberOfPayloadsPerTransaction: 1,\n};\n```\n\n### Standard Use-case\n\nIn this use-case we assume only a single signer is required, as such we provide a singular client which will sign the transaction.\n\nTo create the client:\n\n```javascript\nconst clientConfig = {\n  apiKey: \"01234567-89ab-cdef-0123-456789abcdef\",\n  privateKey: \"/path/to/private/key\",\n  vaultAccountId: X,\n  testnet: true,\n  apiEndpoint: Y,\n};\nconst client = new FireblocksHederaClient(clientConfig);\n```\n\nOnce the client is created you can simply use it to execute transactions, for example (original source code taken from [here](https://docs.hedera.com/hedera/sdks-and-apis/sdks/accounts-and-hbar/transfer-cryptocurrency)):\n\n```javascript\nconst fromAccountId = await client.getFireblocksAccountId();\nconst amount = new Hbar(1);\nconst destAddress = \"0.0.1234\";\n\n// Create a transaction to transfer 1 HBAR\nconst transaction = new TransferTransaction()\n  .addHbarTransfer(fromAccountId, amount.negated())\n  .addHbarTransfer(destAddress, amount);\n\n//Submit the transaction to a Hedera network\nconst txResponse = await transaction.execute(client);\n\n//Request the receipt of the transaction\nconst receipt = await txResponse.getReceipt(client);\n\n//Get the transaction consensus status\nconst transactionStatus = receipt.status;\n\nconsole.log(\n  `Transaction ${txResponse.transactionId.toString()} finished with ${transactionStatus.toString()}`\n);\n\n//v2.0.0\n```\n\nThis way, the client will sign the transaction and perform all needed operations that are non-Fireblocks related.\n\n### Multiple Signers\n\nSome transactions in Hedera might require multiple signers, for example creating a token.\n\nWe first want to create a client, similar to how we did before:\n\n```javascript\nconst clientConfig = {\n  apiKey: \"01234567-89ab-cdef-01234-56789abcdef0\",\n  privateKey: \"/path/to/private/key\",\n  vaultAccountId: X,\n  testnet: true,\n  apiEndpoint: Y,\n};\nconst client = new FireblocksHederaClient(clientConfig);\n```\n\nOnce created, we want to create signers that will be used for the different vault accoutns we need signatures from, this can be done with a custom function called `getSigner` we added to our provided client:\n\n```javascript\nconst adminVaultAccountId = Z;\nconst adminSigner = await client.getSigner(adminVaultAccountId);\nconst adminPublicKey = (await adminSigner.getAccountInfo()).key;\n\nconst treasuryVaultAccountId = W;\nconst treasurySigner = await client.getSigner(treasuryVaultAccountId);\n```\n\nFinally, you can use the provided client and signers to execute the transaction(code taken from [here](https://docs.hedera.com/hedera/sdks-and-apis/sdks/token-service/define-a-token));\u003cbr/\u003e\n**Note** - the below code is slightly changed:\n\n1. The `sign` function calls is replaced with `signWithSigner` function calls.\n2. the `adminPublicKey` uses the above value instead of some inline value\n\n```javascript\n//Create the transaction and freeze for manual signing\nconst transaction = await new TokenCreateTransaction()\n  .setTokenName(\"Your Token Name\")\n  .setTokenSymbol(\"F\")\n  .setTreasuryAccountId(treasurySigner.getAccountId())\n  .setInitialSupply(5000)\n  .setAdminKey(adminPublicKey)\n  .setMaxTransactionFee(new Hbar(30)); //Change the default max transaction fee\n\n// Add the signers to the client, this can be done multiple times if more than 2 signers are needed\nawait client.addSigner(`${adminVaultAccountId}`);\nawait client.addSigner(`${treasuryVaultAccountId}`);\n\n// sign the transaction with all signers and broadcast, the execute method will also cache the signatures if multiuple nodes are configured in the client config\nlet txResponse = await transaction.execute(client);\n\n//Get the receipt of the transaction\nconst receipt = await txResponse.getReceipt(client);\n\n//Get the token ID from the receipt\nconst tokenId = receipt.tokenId;\n\nconsole.log(\n  `Token Create Transaction ${txResponse.transactionId.toString()} finished with ${transactionStatus.toString()}`\n);\n\n//v2.0.5\n```\n\n## Example files\n\nIncluded in this SDK are [four example files](./examples) showcasing different use cases:\n\n- **HBAR Transfer** - Using the SDK with a single signer AND limiting the number of nodes to one.\n- **HBAR Transfer** - Using the SDK with a single signer AND no limit to the number of nodes.\n- **Token Creation** - Using the SDK with two signers AND limiting the number of nodes to one.\n- **Token Creation** - Using the SDK with two signers AND no limit to the number of nodes.\n\n### How to run the example scripts\n\n1. Clone the repo\n2. Install the dependencies\n\n```\nnpm install\n```\n\n3. Update the client config parameters\n4. Run the example script\n\n```\nnpx ts-node examples/script-name.ts\n```\n\n**OR**\n\n```\nnpm run example01\nnpm run example02\nnpm run example03\nnpm run example04\n```\n\n### Successful execution\n\n**HBAR Transfer**\n\n```\n\nTransaction 0.0.4363872@1730366816.250676454 finished with SUCCESS\n\n```\n\n**Token Creation**\n\n```\n\nToken Create Transaction 0.0.4338434@1730471891.681xxx finished with SUCCESS\n\n```\n\n## Configuration\n\nThe following is the configuration used for the Fireblocks Hedera client setup:\n\n```javascript\n    /**\n     * The API User's private key's path\n     */\n    secretKeyPath: string;\n\n    /**\n     * The API User's API key\n     */\n    apiKey: string;\n\n    /**\n     * The vault account to use\n     */\n    vaultAccountId: number;\n\n    /**\n     * Is it testnet\n     */\n    testnet?: boolean;\n\n    /**\n     * The API Endpoint to use, if such is relevant (sandbox, production, etc.)\n     */\n    apiEndpoint?: BasePath;\n\n    /**\n     * Hedera SDK allows for signing the same transaction for multiple nodes. This allows us to\n     * send the transaction to various nodes until one of them accepts it.\n     * This means that for each payload we submit a raw signing transaction.\n     * If not specified in the clientConfig, the default will be multiple node transactions.\n     */\n    maxNumberOfPayloadsPerTransaction?: number;\n```\n\n##License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffireblocks%2Fhbar-fireblocks-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffireblocks%2Fhbar-fireblocks-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffireblocks%2Fhbar-fireblocks-sdk/lists"}