Zero-config connect

What you’ll get here

how connectToCluster({ network }) takes you from a network name to a cluster — and the bootstrap escape hatch for private deployments.

The hardest part of talking to a decentralised network is the chicken-and-egg problem: you need to know where the network is before you can ask it anything. Hardcoding https://some-validator-ip:3000 is brittle — that server might be down, rotated, or never the one you should be talking to.

connectToCluster solves this. You give it a network name; it resolves the network’s entrypoint, asks which clusters are active, and picks one of them at random.

🧠 For Normies

Bootstrapping is the act of finding the network from a single known starting point. Like asking one trusted person for directions, then following the road signs from there. You only have to know the name 'testnet'.

The flow

sequenceDiagram
  participant App as Your app
  participant SDK as SDK
  participant Seed as Canonical gateway (KNOWN_NETWORKS)
  participant Cluster as Chosen cluster gateway

  App->>SDK: connectToCluster({ network: 'testnet', ... })
  SDK->>SDK: resolveNetwork('testnet') → bootstrap seed list
  SDK->>Seed: GET /api/v3/discovery/clusters
  Seed-->>SDK: active cluster set (each with a gatewayUrl)
  SDK->>SDK: random-pick one active cluster
  SDK-->>App: BaasClient bound to that cluster's gateway
  App->>Cluster: baas.authenticate(...) when you need a session

BaasClient.connectToCluster (Host / BaaS)

This is the recommended zero-config entrypoint for smart-apps using the database, storage, functions, messaging, or agents.

1. Connect by network name.

   import { BaasClient } from '@hsuite/smart-engines-sdk';
   
   const baas = await BaasClient.connectToCluster({
     network: 'testnet',
     appId: 'app_abc',
   });
   
   await baas.db.insert('users', { name: 'Alice' });

2. Authenticate when you need a session. BaasClient.connectToCluster returns the client directly (it does not authenticate for you — call baas.authenticate(...) when you need an authenticated session; see Authentication).

It defaults pathPrefix to /host, because cluster discovery hands back the gateway URL and the gateway routes BaaS traffic under /host/*. If you point the SDK at a bare host that isn’t behind a gateway, override with pathPrefix: ''.

Options

Option	Type	Notes
network	'testnet' | 'mainnet' | 'devnet'	Resolves the canonical gateway entrypoint. Mutually exclusive with bootstrap.
bootstrap	string[]	Explicit seed URLs (private deployments). Mutually exclusive with network.
appId	string	Your app id (e.g. from a prior deployment.init())
appName	string	App display name (registration)
pathPrefix	string	Defaults to /host. Set '' to hit a bare host.
timeout	number	Request timeout in ms (default 30000)
allowInsecure	boolean	Plain HTTP for the URLs you supply (bootstrap seeds, mirror node) — local dev only. Never admits plaintext registry entries.
allowInsecureClusters	boolean	Accept a plaintext gatewayUrl returned by the registry — only for a registry you run locally. Never implied by allowInsecure.
trustAnchor	{ network, registryTopicId, mirrorNodeUrl?, onFailure?, expectedValidatorKeys }	Optional on-chain HCS gate over the discovery response: every nodeId must be registered and each record must bind the advertised gatewayUrl. expectedValidatorKeys maps each nodeId to the Ed25519 public key (hex) that must have signed its registry record; an unsigned or wrongly signed record is rejected. onFailure defaults to 'reject' (a mirror error or an empty registry throws TrustAnchorError); 'passthrough' is a non-production opt-in that returns the seed’s list unverified. The testnet registry topic is 0.0.9143793.

Refuses, never degrades.

If a seed answers with a cluster list in which no gateway is https://, connectToCluster throws InsecureClusterRegistryError (it names the seed and the rejected entries) rather than returning “no clusters”. That registry is serving cleartext and has to be fixed server-side — do not paper over it with allowInsecure, which would not help anyway. A list that mixes secure and plaintext entries silently drops the plaintext ones.

Validator raw tier — retired

Earlier SDK versions shipped a second, validator-direct profile (SmartEngineClient + connectToNetwork) for raw-tier operations — accounts, tokens, transfers, TSS, IPFS, transaction preparation against /api/v3/{transactions,tss,ipfs,tokens,...}. As of SDK 8.0 it is retired: that tier has no public origin — the public gateway does not route it, and the on-chain validator registry publishes only a gatewayUrl, never a validator API endpoint — so connectToNetwork could never reach a deployed network. BaasClient.connectToCluster (above) is now the only public entrypoint. Transfers move through the entity-scoped surface instead:

import { BaasClient } from '@hsuite/smart-engines-sdk';

const baas = await BaasClient.connectToCluster({ network: 'testnet', appId: 'app_abc' });
await baas.authenticate({ chain: 'xrpl', walletAddress: wallet.address, publicKey: wallet.publicKey, signFn: sign });

const result = await baas.entities.transfer('entity-1', {
  chain: 'xrpl',
  to: 'rDestination...',
  amount: '1000000', // drops
});

See the 8.0 CHANGELOG entry for the full migration.

The bootstrap escape hatch

For private deployments, local clusters, or pinning your own seed order, pass bootstrap instead of network:

const baas = await BaasClient.connectToCluster({
  bootstrap: ['https://gateway.my-private-net.example'],
  appId: 'app_abc',
});

Passing both network and bootstrap is a compile-time TypeScript error — the config is a discriminated union, so the type system stops the “which one wins?” ambiguity before runtime.

🧠 For Normies

A trust anchor is an on-chain record (an HCS topic) listing which validators are legitimately part of the network and which gateway each one serves. Passing trustAnchor makes the SDK gate the discovery response against the chain: a cluster is used only if every node it claims is on-chain and the chain says those nodes serve that exact gateway, so a hacked seed URL can’t point you at an attacker’s gateway by quoting real node ids. If the chain can’t be read (or the registry is empty), the SDK refuses to connect rather than guessing — unless you explicitly set onFailure: 'passthrough'. Without trustAnchor, you get the same trust model as a plain HTTPS call to a public endpoint.

Known networks

The SDK ships canonical entrypoints in KNOWN_NETWORKS:

Network	Bootstrap entrypoint
testnet Live	https://gateway.testnet.hsuite.network
mainnet	https://gateway.hsuite.network Reserved
devnet	https://gateway.develop.hsuite.network Reserved

The testnet is live on HSuite-operated validators. It opens to developers once the security audit is complete.

“Reserved” means the name resolves and type-checks today, but the network is not deployed for public use: discovery against it fails at runtime with the ordinary “no cluster reachable” error rather than a compile-time “unknown network” surprise. Mainnet has no date.

For testnet the SDK also ships the validator-registry anchor (the registry topic and each validator’s signing key) used to verify post-quantum attestations.

Customers who run their own validators should not extend this map — pass bootstrap: [...] directly instead.

Picking a network from an env var

networkFromEnv(explicit, env) resolves a NetworkName the same way the CLI does: an explicit value you already have wins outright, otherwise env.HSUITE_NETWORK is used if it names a known network, otherwise testnet.

import { networkFromEnv } from '@hsuite/smart-engines-sdk';

const baas = await BaasClient.connectToCluster({
  network: networkFromEnv(undefined, process.env), // reads $HSUITE_NETWORK, else 'testnet'
  appId: 'app_abc',
});

Errors

Condition	Thrown
No cluster reachable via any seed	503
Neither a known network nor a non-empty bootstrap list	400
A seed returned only plaintext gateways	InsecureClusterRegistryError
trustAnchor set (with onFailure: 'reject') and the registry can’t be read or is empty	TrustAnchorError

Next steps

AuthenticationAdd wallet auth.

TransactionsMove value from an entity you own.

SDK overviewBack to the SDK overview.