Installation

What you’ll get here

the exact install command, the peer dependencies you need depending on which chain you sign with, and which runtimes the SDK supports.

Install

npm

npm install @hsuite/smart-engines-sdk xrpl zod

yarn

yarn add @hsuite/smart-engines-sdk xrpl zod

pnpm

pnpm add @hsuite/smart-engines-sdk xrpl zod

The package name is @hsuite/smart-engines-sdk. It ships compiled JavaScript plus bundled .d.ts types — no separate @types package, no build step on your side.

🧠 For Normies

A peer dependency is a library the SDK expects you to install yourself, instead of bundling its own copy. This avoids two clashing versions of, say, the XRPL library ending up in your project.

Peer dependencies

The SDK keeps its own dependency list small and declares the larger libraries as peer dependencies. Two are required; the rest are optional:

Peer dependency	Version range	When you need it
xrpl	^4.0.0 || ^3.0.0	Required the main entry point loads it. Also used by createXrplWeb3Signer (XRPL is the default auth chain)
zod	^3.23.0	Required the main entry point loads it for request validation
@hashgraph/sdk	^2.62.0	Optional only when you sign with a Hedera key
@nestjs/common, @nestjs/core	^10 || ^11	Optional only for the NestJS integration subpath
rxjs	^7.0.0	Optional only for the NestJS integration subpath

A typical XRPL-based smart-app needs exactly the install command above. A Hedera app adds @hashgraph/sdk.

Import surfaces

The package has a main entry point and seven subpaths. Pick the one you need so your bundle stays lean:

flowchart TD
  Main["@hsuite/smart-engines-sdk"] --> Clients["BaasClient / SmartGatewayClient + auth + subscription/faucet/resources/personhood"]
  Nest["@hsuite/smart-engines-sdk/nestjs"] --> NestMod["SmartEngineModule + guards"]
  Pqc["@hsuite/smart-engines-sdk/pqc-verify"] --> Verify["verifyPqcAttestation (post-quantum)"]
  Sess["@hsuite/smart-engines-sdk/customer-session"] --> SessC["CustomerSessionClient"]
  Intent["@hsuite/smart-engines-sdk/entity-create-intent"] --> IntentF["signed entity-create intents"]

// Main surface — the public clients, auth, subscriptions, etc.
import { BaasClient, SmartGatewayClient } from '@hsuite/smart-engines-sdk';

// NestJS module, guards and decorators (keeps @nestjs/* out of the main bundle)
import { SmartEngineModule } from '@hsuite/smart-engines-sdk/nestjs';

// Post-quantum attestation verifier (keeps @noble/post-quantum out of bundles that don't verify)
import { verifyPqcAttestation } from '@hsuite/smart-engines-sdk/pqc-verify';

The other three subpaths are narrower helpers: pqc-verify-envelope (structural checks on a post-quantum encryption envelope, no decryption), ipfs-access-key (retrieve and decrypt an IPFS access key), and k8s-secret-reader (decrypts secret values the platform writes; it needs the cluster’s own key, so it serves platform components, not apps).

🧠 For Normies

A subpath export like /nestjs is a separate door into the same package. The SDK puts heavy or framework-specific code behind these doors so your bundle stays small if you don’t open them.

Supported runtimes

The SDK is marked side-effect-free, and the main entry point’s HTTP layer uses only the standard fetch and AbortController APIs.

Node.js

^22.23.4, ^24.22.1 or >=26.12.1 (the package’s engines range)

Node-only subpaths

/nestjs and /k8s-secret-reader use Node APIs

Versioning

The current line is @hsuite/[email protected] (latest 13.0.1). The SDK follows semantic versioning:

• A minor bump (e.g. 6.0 → 6.1) can add new clients, methods, optional arguments, or a new known network entry.
• A major bump signals a breaking change to an existing method signature or response shape.

Pin a caret range (^13.0.1) to get non-breaking updates automatically.

Version notes

4.0.0 (breaking) type-fenced the two client profiles: SmartEngineClient became the validator-direct profile and took an explicit validatorBaseUrl (never a gateway URL); its old connectToCluster factory was removed. Reach a cluster through the host tier with BaasClient.connectToCluster({ network }) instead. It also added the entities value-movement surface. Later 4.x minors added primaryChain on AgentRegisterRequest (4.1.0) and the executable payer-funded agent (4.2.0).

5.x rounds out the smart-app surface: the two-phase payer-funded EntitiesClient create flow (prepareCreate* / executeCreate*), the provider-agnostic AI inference helper (createModelProvider / inferJson over Anthropic / OpenAI / Gemini), and agent/BaaS completeness — agents.certification(), agents.execute(), the onBehalfOf owner-acting option, storage.downloadWithMeta(), functions.getCode(), and error helpers (isRuleRejected). Later 5.x minors added the deployment-context auth BaasClient.fromEnv + authToken (5.2.0 — see Authentication) and server-side transfer/withdraw broadcast on Hedera and XRPL (5.3.0 — see Transactions). All additions are additive (optional trailing arguments). See the SDK overview.

6.0.0 (breaking) hardened verifyPqcAttestation: verifying a security-bearing consumer (e.g. the on-chain app-registry) requires a validator-registry snapshot, and a minimum quorum floor is enforced. Additive in the same release: composeApps({ network | bootstrap, appIds }) for marketplace multi-app client wiring.

6.1.0 lets functions.signCode() carry a stable, registerable signing identity: configure functionSigningKey once (on BaasClient or the FunctionsClient constructor) and every signCode() / deploy() / eval() reuses it instead of minting a throwaway keypair per call, so a cluster’s trusted-signer allowlist can match it. Adds the generateBaasFunctionSigningKey() and baasFunctionSignerAllowlistHex() exports. Not breaking — configuring a key is opt-in.

6.2.0 carries per-app egress declaration — a deployed smart-app’s outbound network access is default-deny, and the deploy manifest’s backend.egress list is how you request the external hosts your app may reach. See CLI → reaching the outside world. Not breaking — omitting egress leaves any prior declaration in place.

6.3.0 adds devnet as a known network target alongside testnet and mainnet: network: 'devnet' / HSUITE_NETWORK=devnet resolves and type-checks in both the SDK and the CLI. See Zero-config connect → known networks. Not breaking — additive network entry.

7.0.0 (breaking) is a security-hardening release that closes several external-pentest findings; each item below is a breaking change, so read the migration notes before upgrading.

• AgentInfo.owner is renamed AgentInfo.ownerWallet, and agents.list() returns count not total. Both old names were never sent by the host, so owner was always undefined, and a filter like agents.filter(a => a.owner === caller) matched every row. Migration: a.owner → a.ownerWallet, res.total → res.count — audit any authorization decision built on the old field before upgrading.
• New apps default to strict customer-scope. A customer-reachable data-plane call carrying no customer identity is refused 403. Apps stored before this default resolve strict too, so an older app that forwards no customer identity must start forwarding it, or opt out explicitly with hsuite customer-scope permissive. See SDK → forCustomer.
• The PQC verifier anchors to the registry. The registry snapshot is a required parameter for every consumer, an unreachable registry throws RegistryUnavailableError instead of degrading, duplicate signers are rejected, and a cert can no longer declare itself below the quorum floor. payloadHash must agree with contentHash; an opt-in maxAgeMs policy bounds replay.
• SmartEngineModule authenticates the whole app. forRoot / forRootAsync register CustomerSessionGuard as an APP_GUARD — importing the module is enough. Migration: mark genuinely anonymous routes @Public() (health probes, the login handshake) or they will start answering 401. See SDK → guarding your own backend.
• The cluster-discovery trustAnchor is a gate, and the SDK refuses cleartext registries. A cluster passes only if every claimed nodeId is on-chain and each record binds the advertised gatewayUrl; a registry that can’t be read or is empty throws TrustAnchorError, and a registry advertising a plaintext gateway is refused with InsecureClusterRegistryError. See Zero-config connect.

See the CHANGELOG for the full 7.0.0 detail.

8.0.0 (breaking) retires the validator-direct raw tier from the public SDK. SmartEngineClient and everything that existed only to serve it (connectToNetwork, TSSClient, IPFSClient, TransactionsClient + its chain-namespaced siblings, TokensClient, SettlementClient, GovernanceClient, DaoClient, BridgeClient, EnvelopeClient, OperatorClient, SnapshotsClient, HistoricalBalanceClient) is no longer exported — none of those paths are reachable through the public gateway, and the on-chain registry publishes only a gatewayUrl, never a validator API endpoint. BaasClient is now the only public path to web3; entity-scoped value movement (baas.entities.transfer / .prepareWithdraw / .executeWithdraw / .mint / .burn / .compliance / .trustline) replaces the retired client.transactions.*. SubscriptionClient, FaucetClient, ResourcesClient and PersonhoodClient stay exported as standalone clients you point at the gateway with createHttpClient. See Zero-config connect → validator raw tier and the CHANGELOG for the before/after migration snippet.

8.1.0 adds signed entity-create intents to the package root: signEntityCreateIntent(signer, { network, entityType, chain, rule }) builds and signs a requestor-signed create intent (fresh random nonce, 10-minute TTL) with the same chain-agnostic { chain, walletAddress, publicKey?, signFn } signer shape BaasClient.authenticate already uses — so a customer create carries proof the developer’s wallet chose the rule and entity identity. Also exported: buildDefaultSmartAppValidatorRules() / buildDefaultAgentValidatorRules() and assertCreatedEntityMatchesIntent(returnedId, expectedEntityId). The SDK still never signs on the caller’s behalf — signFn stays yours.

8.1.0 also changes one verifier default. verifyPqcAttestation no longer verifies a cert of any age when you omit a freshness bound: pass { maxAgeMs } with the oldest cert age you accept, or { maxAgeMs: Infinity } to verify a historical record deliberately. Without it the result is { valid: false, reason: 'freshness-policy-required' }, and hsuite verify requires --max-age <ms|infinity>.

8.2.0 adds payer-signed deposit-wallet intents: signDepositWalletIntent(signer, { network, depositType, chain, tokenId, appId? }) signs the canonical deposit rule the SDK builds client-side, and a smart-app create carries it as depositCreationIntent next to its own creationIntent. Upgrade the SDK and @hsuite/smart-engines-cli (2.0.0 or later) together. 8.2.0 also adds the types for paying a subscription in XRP: DepositInstructions.pay, SubscriptionOrder.xrp / .conversion, and isXrpQuoteUnavailableError. XRP payment is built, not yet enabled. DaoVotingPowerModel is now 'token-balance' only.

9.0.0 (major) @hashgraph/sdk is now an optional peer: a Hedera app must list @hashgraph/sdk in its own dependencies (npm install @hashgraph/sdk); an XRPL-only app installs none of the Hedera stack. The listing content hash now excludes hostingUrl, so upgrade every verifier to 9.0.0. Use @hsuite/smart-engines-cli 2.1.0 with it.

10.0.0 (breaking) binds verifyPqcAttestation to the HCS-anchored validator registry. Its third argument is now RegistryEvidence — await fetchRegistrySnapshotFromMirror({ network }), the validators’ own Ed25519-signed registry rows — and the policy names the anchor (network for the pins the SDK ships, or your own anchor). A served {snapshotTs, validators} snapshot returns registry-snapshot-unanchored: whoever served it chose the keys. fetchRegistrySnapshot, fetchRegistrySnapshotQuorum, fetchRegistrySnapshotFromClusters, computeSnapshotHash and ValidatorRegistrySnapshotSchema are removed; reconstructListingSet takes registry + network/anchor instead of snapshot. Use @hsuite/smart-engines-cli 3.0.0 with it.

11.0.0 (breaking) makes every BaaS client send exactly what the host serves. Agents take rulesConfig/type/a sync primaryChain; trade takes baseToken/quoteToken; entity creates name who pays (platformPaid or fundWith); customerSession.login retries the cross-cluster challenge miss. Use @hsuite/smart-engines-cli 3.1.0 with it.

12.0.0 (breaking) makes the baas.entities create methods wait for the outcome by default wherever the host admits the create asynchronously: the Hedera platformPaid createToken / createAccount / createTopic, and the XRPL token and account drafts (prepareCreateToken / executeCreateToken / prepareCreateAccount / executeCreateAccount, and the XRPL fundWith conveniences). Each is admitted with wait: false and a per-call idempotency key, then the SDK follows GET /api/v3/baas/operations/:id and resolves the same result as before; { wait: false } returns the 202 admission instead. The return types are now unions with AdmittedOperation (narrow with baas.isAdmittedOperation from the baas namespace export), a wait can throw OperationPendingError / OperationAbortedError, and baas.operations.get / .wait follow an operation by id. The Hedera fundWith two-phase and createAgent stay synchronous. DomainTransferRequest is now { newOwner }. Use @hsuite/smart-engines-cli 3.2.0 with it.

13.0.0 (breaking) deletes MarketplaceClient.buy and its types (MarketplaceBuyEscrow, MarketplaceBundleBuyResult, MarketplaceBuyResult) and the 'marketplace-sale' deposit type: the platform-mediated buy is gone. A subscription purchase is one atomic XRPL Batch. quotePurchase(appId, buyer) returns the Batch, already co-signed by the app’s subscription issuer and checked with checkPurchaseQuote; the buyer’s wallet signs and submits it; confirmPurchase(appId, txHash) returns the receipt once all four inner transactions settled. linkSubscriptionIssuer(appId, { creationIntent }) links the app’s issuer. Use @hsuite/smart-engines-cli 3.3.0 with it.

Next steps

Zero-config connectConnect to a cluster.

AuthenticationSet up wallet authentication.

SDK overviewBack to the SDK overview.