|
| 1 | +# Migrating to `helius-sdk` 2.0.0 |
| 2 | + |
| 3 | +The Helius Node.js SDK has been rewritten on top of [`@solana/kit`](https://github.com/anza-xyz/kit), replacing the dependency on `@solana/web3.js` (>1.73.2). The goal: keep DevEx familiar while improving ergonomics, performance, and type safety while supporting the latest Solana developments. |
| 4 | + |
| 5 | +The TLDR is most method names are unchanged. What has changed is their namespace and the exact types, reflecting the latest types via Kit. |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## 1) Installation |
| 10 | + |
| 11 | +```bash |
| 12 | +# Install the SDK |
| 13 | +npm i helius-sdk |
| 14 | + |
| 15 | +# Optional: install Kit if you need to use their helpers directly in your app |
| 16 | +npm i @solana/kit |
| 17 | +``` |
| 18 | + |
| 19 | +## 2) Quickstart |
| 20 | + |
| 21 | +### Before 2.x |
| 22 | +```typescript |
| 23 | +import { Helius } from "helius-sdk"; |
| 24 | +import { PublicKey } from "@solana/web3.js; |
| 25 | + |
| 26 | +const helius = new Helius(process.env.HELIUS_API_KEY); |
| 27 | +const assets = await helius.getAssetsByOwner({ ownerAddress: "..." }); |
| 28 | +``` |
| 29 | +### After 2.x |
| 30 | +```typescript |
| 31 | +import { createHelius } from "helius-sdk"; |
| 32 | +import { address } from "@solana/kit"; |
| 33 | + |
| 34 | +const helius = createHelius({ apiKey: process.env.HELIUS_API_KEY! }); |
| 35 | +const assets = await helius.getAssetsByOwner({ ownerAddress: address("...") }); |
| 36 | +``` |
| 37 | + |
| 38 | +## 3) Import Paths and Tree-shaking |
| 39 | +This package is ESM-first (i.e., `"type": "module"`). Use `import`, not `require`. |
| 40 | + |
| 41 | +The root is the `src` dir, with the main functionality deriving from the `createHelius` function. There are also subpaths for more granular tree-shaking: |
| 42 | +- RPC methods: `import "helius-sdk/rpc/methods/<>` |
| 43 | +- Enhanced Transactions API: `import "helius-sdk/enhanced/<>` |
| 44 | +- Staking: `import "helius-sdk/staking/<>` |
| 45 | +- Transactions: `import "helius-sdk/transactions/<>` |
| 46 | +- Types: `import type { Foo } from "helius-sdk/types/<>` |
| 47 | +- Webhooks: `import "helius-sdk/webhooks/<>` |
| 48 | +- WebSockets: `import "helius-sdk/websockets/<>` |
| 49 | +- ZK: `import "helius-sdk/zk/<>` |
| 50 | + |
| 51 | +Note, the SDK is designed such that these granular imports are not 100% necessary. The package sets `sideEffects` to `false`, meaning bundlers can safely tree-shake unusued code. |
| 52 | + |
| 53 | +## 4) Migration Cheatsheet |
| 54 | +| Area | 1.x | 2.x | |
| 55 | +|----------------|------------------------------------------|-------------------------------------------------| |
| 56 | +| Client init | `new Helius()` | `createHelius()` | |
| 57 | +| Public key | `new PublicKey(str)` | `address(str)` | |
| 58 | +| Amounts | `new BN(...)` / Number(...) | `lamports(...n)` | |
| 59 | +| Signer | `Keypair.fromSecretKey(bs58.decode(""))` | `createKeyPairSignerFromBytes(bs58.decode(""))` | |
| 60 | +| Transactions | `helius.rpc.<method>` | `helius.tx.<method>` | |
| 61 | +| DAS API | `helius.rpc.<method>` | `helius.<method>` | |
| 62 | +| Staking | `helius.rpc.<method>` | `helius.stake.<method>` | |
| 63 | +| Webhooks | `helius.<method>` | `helius.webhooks.<method>` | |
| 64 | +| Enhanced Tx | No support | `helius.enhanced.<method>` | |
| 65 | +| ZK Compression | No support | `helius.zk.<method>` | |
| 66 | +| WebSockets | @solana/web3.js subscriptions | `helius.ws.<method>` | |
| 67 | + |
| 68 | +## 5) Breaking Changes |
| 69 | +1. Client Construction: `createHelius()` factory instead of `new Helius()` |
| 70 | +2. Kit Primitives: prefer `address()`, `lamports()`, and other helpers provided by Kit |
| 71 | +3. Full Helius Support: can now use ZK Compression, the Enhanced Transactions API, WebSockets, and Sender via the SDK |
| 72 | +4. Deprecated Jito Methods: prefer [Sender](https://www.helius.dev/docs/sending-transactions/sender) for transaction submission |
| 73 | +5. `editWebhook` is renamed to `update` |
| 74 | +6. ESM-Only: use `import`; if using CommonJS, transpile or use dynamic `import()` |
| 75 | + |
| 76 | +## 6) Endpoint Mapping |
| 77 | +- DAS (`helius.`): `getAsset`, `getAssetBatch`, `getAssetProof`, `getAssetProofBatch`, `getAssetsByAuthority`, `getAssetsByCreator`, `getAssetsByGroup`, `getAssetsByOwner`, `getNftEditions`, `getTokenAccounts`, `searchAssets` |
| 78 | +- RPC V2 (`helius.`): `getProgramAccountsV2`, `getTokenAccountsByOwnerV2`, `getAllProgramAccounts`, `getAllTokenAccountsByOwner` |
| 79 | +- Priority Fee API (`helius.`): `getPriorityFeeEstimate` |
| 80 | +- Enhanced Transactions API (`helius.enhanced.`): `getTransactions`, `getTransactionsByAddress` |
| 81 | +- Staking (`helius.stake.`): `createStakeTransaction`, `createUnstakeTransaction`, `createWithdrawTransaction`, `getHeliusStakeAccounts`, `getStakeInstruction`, `getUnstakeInstruction`, `getWithdrawInstruction`, `getWithdrawableAmount` |
| 82 | +- Transactions (`helius.tx.`): `broadcastTransaction`, `getComputeUnits`, `pollTransactionConfirmation`, `createSmartTransaction`, `sendSmartTransaction`, `sendTransactionWithSender`, `sendTransaction` |
| 83 | +- Webhooks (`helius.webhooks.`): `create`, `get`, `getAll`, `update`, `delete` |
| 84 | +- WebSockets (`helius.ws.`): `logsNotifications`, `slotNotifications`, `signatureNotifications`, `programNotifications`, `accountNotifications`, `close` |
| 85 | +- ZK Compression (`helius.zk.`): `getCompressedAccount`, `getCompressedAccountProof`, `getCompressedAccountsByOwner`, `getCompressedBalance`, `getCompressedBalanceByOwner`, `getCompressedMintTokenHolders`, `getCompressedTokenAccountBalance`, `getCompressedTokenAccountsByDelegate`, `getCompressedTokenAccountsByOwner`, `getCompressedTokenBalancesByOwner`, `getCompressedTokenBalancesByOwnerV2`, `getCompressionSignaturesForAccount`, `getCompressionSignaturesForAddress`, `getCompressionSignaturesForOwner`, `getCompressionSignaturesForTokenOwner`, `getIndexerHealth`, `getIndexerSlot`, `getLatestCompressionSignatures`, `getLatestNonVotingSignatures`, `getMultipleCompressedAccountProofs`, `getMultipleCompressedAccounts`, `getMultipleNewAddressProofs`, `getMultipleNewAddressProofsV2`, `getTransactionWithCompressionInfo`, `getValidityProof`, `getSignaturesForAsset` |
| 86 | + |
| 87 | +## 7) FAQ |
| 88 | +**Do I need to change my RPC URL?** |
| 89 | +- No, your existing Helius RPC URL still works. |
| 90 | + |
| 91 | +**Do I need to install `@solana/kit`?** |
| 92 | +- While not strictly required since the SDK bundles it internally, you'll likely have to install Kit to use its helpers throughout your codebase. Please refer to [Kit's documentation site](https://www.solanakit.com/) for any Kit-related troubleshooting. |
| 93 | + |
| 94 | +**Is 1.x deprecated?** |
| 95 | +- Yes. We recommend everyone updates to a 2.x version in accordance to the latest developments on Solana. We will be maintaining 2.x versions going forward. |
| 96 | + |
| 97 | +**Why the migration?** |
| 98 | +- Smaller bundles, faster cold start in edge runtimes, better types, cleaner codebase that's easier to maintain and contribute to, more complete Helius support, and to stay up-to-date with the latest Solana developments. |
| 99 | + |
| 100 | +## 8) Examples |
| 101 | +See the [`examples` directory](https://github.com/helius-labs/helius-sdk/tree/main/examples), organized by namespace, for example implementations for: |
| 102 | +- DAS (assets, proofs, fetching program accounts) |
| 103 | +- Transactions (creating optimized transactions, Sender) |
| 104 | +- Staking (how to stake with Helius, as well as any staking-related functionality) |
| 105 | +- Enhanced Transactions (fetching transactions for a given address or addresses) |
| 106 | +- Webhooks (programmatic event-driven updates) |
| 107 | +- WebSockets (listening to accounts for specific updates) |
| 108 | + |
| 109 | +## 9) Support |
| 110 | +- Docs: https://www.helius.dev/docs |
| 111 | +- Discord: https://discord.com/invite/6GXdee3gBj |
| 112 | +- Chat support: https://dashboard.helius.dev/support |
| 113 | +- Email support: [email protected] |
0 commit comments