# How the StarshipJS Library Facilitates Interchain Development: A Complete Guide

> Discover how StarshipJS simplifies interchain development with its TypeScript SDK. Manage multi-chain configurations, load registries, and access chain hooks via a unified API. Build across blockchains seamlessly.

- Repository: [Hyperweb/starship](https://github.com/hyperweb-io/starship)
- Tags: how-to-guide
- Published: 2026-03-03

---

**StarshipJS is a TypeScript SDK that abstracts the complexity of multi-chain interactions by providing a singleton configuration manager, dynamic chain registry loading, and per-chain hooks that expose RPC endpoints, genesis keys, and faucet functionality through a unified API.**

The StarshipJS library, maintained in the `hyperweb-io/starship` repository, enables developers to build and test applications across multiple blockchain networks without hard-coding endpoints or manually parsing chain registry files. By leveraging a declarative YAML configuration and a set of modular TypeScript hooks, the SDK transforms interchain development from a complex integration task into a streamlined configuration-driven workflow.

## Understanding the StarshipJS Architecture

StarshipJS follows a layered architecture designed to separate configuration management from chain-specific operations. The library exposes four primary components through its public API: a singleton configuration class, registry initialization hooks, per-chain utility hooks, and wallet generation helpers. This modular design ensures that developers initialize the SDK once and then access any declared chain through a consistent interface.

## Centralized Configuration with the Config Singleton

The foundation of StarshipJS interchain development is the `Config` class defined in [`src/config.ts`](https://github.com/hyperweb-io/starship/blob/main/src/config.ts). This singleton stores the path to your Starship YAML configuration file and maintains a `ChainRegistryFetcher` instance that aggregates chain metadata.

By enforcing singleton behavior, `Config` guarantees that every module in your application references the same registry data and configuration context. The class exposes `Config.init(pathToConfig)` for initialization and `Config.registry` for direct access to the underlying fetcher, enabling advanced use cases where you need to enumerate all available chains programmatically.

## Dynamic Chain Registry Loading via useRegistry

Before you can interact with specific chains, StarshipJS must parse the YAML configuration and hydrate the chain registry. The `useRegistry` function in [`src/hooks.ts`](https://github.com/hyperweb-io/starship/blob/main/src/hooks.ts) orchestrates this process.

When invoked, `useRegistry` reads the Starship YAML file, constructs HTTP URLs pointing to the local Chain Registry service, instantiates a `ChainRegistryFetcher` from `@chain-registry/client`, and eagerly fetches all chain-specific JSON descriptors. This initialization phase transforms static configuration into a living registry object that contains up-to-date RPC endpoints, REST URLs, and asset metadata for every chain declared in your YAML file.

## Per-Chain Development with useChain

Once the registry is initialized, the `useChain(chainName)` function becomes the primary interface for interchain development. Located in [`src/hooks.ts`](https://github.com/hyperweb-io/starship/blob/main/src/hooks.ts), this function returns a **ChainHook** object that bundles essential primitives for interacting with a specific blockchain.

### Accessing Endpoints and Chain Information

The ChainHook exposes `chain` and `chainInfo` properties containing raw registry objects for the requested chain. For network connectivity, `getRpcEndpoint()` and `getRestEndpoint()` compute local RPC and REST URLs based on the port mappings defined in your YAML configuration, eliminating the need to hard-code localhost addresses or manage port numbers manually.

### Genesis Keys and Faucet Integration

For testing and development workflows, `useChain` provides critical utilities for account management and funding. The `getGenesisMnemonic()` method retrieves the genesis key generated by the Starship local-network generator, enabling programmatic signing of the first block. The `getCoin()` method returns the first asset listed for the chain, which is essential for constructing token transfer messages.

Most importantly, `creditFromFaucet(address, denom?)` posts to the chain-specific faucet endpoint to fund any address with the chosen denomination. This integration allows developers to programmatically provision test accounts without manual CLI interactions or external funding scripts.

## Wallet Generation and Utility Helpers

StarshipJS includes utility functions to support wallet creation for testing purposes. The [`src/utils.ts`](https://github.com/hyperweb-io/starship/blob/main/src/utils.ts) file re-exports `generateMnemonic` from the `bip39` library, allowing developers to create fresh HD wallets when spinning up new test accounts. This helper integrates seamlessly with the faucet functionality, enabling complete programmatic workflows from account generation to funding.

## Complete Implementation Example

The following example demonstrates a complete interchain development workflow using StarshipJS:

```typescript
// 1️⃣ Initialise the SDK (run once at app start)
import { Config } from '@starshipjs';

// Path to the Starship YAML generated by `starship init`
await Config.init('./starship.yml');

// 2️⃣ Obtain a hook for a specific chain (e.g., Osmosis)
import { useChain, generateMnemonic } from '@starshipjs';

const osmo = useChain('osmosis');
if (!osmo) throw new Error('Chain not found');

// Get RPC endpoint for direct Tendermint queries
const rpc = await osmo.getRpcEndpoint();   // http://localhost:26657

// Fetch the chain's native token information
const coin = await osmo.getCoin();         // { base: 'uosmo', ... }

// Generate a fresh test account and fund it from the local faucet
const mnemonic = generateMnemonic();        // 12‑word seed phrase
const address = /* derive address from mnemonic */;
await osmo.creditFromFaucet(address, coin.base);

```

```typescript
// 3️⃣ Using the registry directly (advanced)
import { Config } from '@starshipjs';

// After Config.init(...)
const registry = Config.registry;   // ChainRegistryFetcher instance

// List all registered chains
const allChains = registry.getChains();   // [{ chainName: 'cosmoshub', ... }, …]

```

## Summary

- **StarshipJS** provides a TypeScript SDK that abstracts interchain complexity through a configuration-driven architecture.
- The **`Config` singleton** in [`src/config.ts`](https://github.com/hyperweb-io/starship/blob/main/src/config.ts) ensures centralized management of YAML configuration and chain registry data.
- **`useRegistry`** in [`src/hooks.ts`](https://github.com/hyperweb-io/starship/blob/main/src/hooks.ts) dynamically loads chain metadata from local registry services, hydrating the SDK with current network definitions.
- **`useChain`** delivers per-chain utilities including endpoint resolution (`getRpcEndpoint`, `getRestEndpoint`), genesis key retrieval (`getGenesisMnemonic`), and faucet integration (`creditFromFaucet`).
- **Utility functions** like `generateMnemonic` from [`src/utils.ts`](https://github.com/hyperweb-io/starship/blob/main/src/utils.ts) support complete testing workflows from account creation to funding.

## Frequently Asked Questions

### What is the StarshipJS library used for?

StarshipJS is a TypeScript SDK designed for building and testing applications that interact with multiple blockchain networks simultaneously. It abstracts the complexity of managing chain registries, RPC endpoints, and test account funding by providing a unified configuration-driven API that works with the Starship local development environment.

### How does StarshipJS handle chain configuration?

StarshipJS uses a singleton `Config` class defined in [`src/config.ts`](https://github.com/hyperweb-io/starship/blob/main/src/config.ts) to manage chain configuration. Developers initialize this once with `Config.init('./starship.yml')`, which stores the path to a Starship YAML configuration file and maintains a `ChainRegistryFetcher` instance. This ensures all parts of the application reference the same registry data and network definitions without requiring manual URL configuration.

### What methods does useChain provide for interchain development?

The `useChain` hook returns a **ChainHook** object containing several critical methods for blockchain interaction: `getRpcEndpoint()` and `getRestEndpoint()` for retrieving local network URLs; `getGenesisMnemonic()` for accessing the genesis signing key; `getCoin()` for retrieving native asset metadata; and `creditFromFaucet(address, denom?)` for programmatically funding test accounts. These methods abstract away port mappings and service discovery, allowing developers to focus on application logic rather than infrastructure setup.

### How do I fund test accounts when using StarshipJS?

StarshipJS provides the `creditFromFaucet` method available through the `useChain` hook. After generating a mnemonic using `generateMnemonic()` from [`src/utils.ts`](https://github.com/hyperweb-io/starship/blob/main/src/utils.ts) and deriving the corresponding address, you can call `await chain.creditFromFaucet(address, denom)` where `denom` is the base denomination retrieved via `chain.getCoin()`. This posts directly to the chain-specific faucet endpoint defined in your Starship configuration, eliminating the need for manual CLI commands or external funding scripts.