@selendrajs/sdk

A modular, extensible TypeScript SDK for connecting to the Selendra blockchain.

Features

• Modular Architecture - Easy to extend and maintain
• Dual Chain Support - Substrate and EVM chains
• Tree-Shakeable - Import only what you need
• Type-Safe - Full TypeScript with strict mode
• Event-Driven - React to connection changes
• Auto-Reconnect - Built-in reconnection logic
• Well-Documented - Comprehensive JSDoc comments
• Powered by viem - Modern, lightweight EVM library
• wagmi Compatible - Seamless React integration

Project Structure

sdk.ts/
├── src/                        # Source code (modular)
│   ├── index.ts               # Main entry point
│   ├── core/                  # Core SDK functionality
│   ├── providers/             # Chain providers
│   ├── types/                 # Type definitions
│   └── utils/                 # Utilities
├── examples-modular.ts        # Usage examples
├── ARCHITECTURE.md            # Architecture guide
└── package.json

Installation

npm install @selendrajs/sdk
# or
yarn add @selendrajs/sdk
# or
pnpm add @selendrajs/sdk

Quick Start

Connect to Substrate Chain

import { SelendraSDK, ChainType, Network } from "@selendrajs/sdk";

const sdk = new SelendraSDK({
  endpoint: "wss://rpc.selendra.org",
  chainType: ChainType.Substrate,
  network: Network.Selendra,
});

// Listen to events
sdk.on("connecting", () => console.log("Connecting..."));
sdk.on("connected", () => console.log("Connected!"));
sdk.on("disconnected", () => console.log("Disconnected"));
sdk.on("error", (error) => console.error("Error:", error));

// Connect
await sdk.connect();

// Get connection info
const info = sdk.getConnectionInfo();
console.log("Connected to:", info.network);

// Disconnect when done
await sdk.disconnect();

Connect to EVM Chain

import { SelendraSDK, ChainType } from "@selendrajs/sdk";

const sdk = new SelendraSDK({
  endpoint: "https://rpc-evm.selendra.org",
  chainType: ChainType.EVM,
});

await sdk.connect();

// Access the viem public client
const client = sdk.getEvmProvider();
const blockNumber = await client?.getBlockNumber();
console.log("Current block:", blockNumber);

// Get balance using viem
const balance = await client?.getBalance({
  address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
});

await sdk.disconnect();

API Reference

Class: SelendraSDK

Main SDK class for connecting to Selendra blockchain.

Constructor

new SelendraSDK(config?: SDKConfig)

Parameters:

• config (optional): SDK configuration object

Example:

const sdk = new SelendraSDK({
  endpoint: "wss://rpc.selendra.org",
  network: Network.Selendra,
  chainType: ChainType.Substrate,
  timeout: 30000,
  retryAttempts: 3,
  retryDelay: 1000,
  autoReconnect: true,
  debug: false,
});

Methods

connect(): Promise<void>

Connect to the blockchain network.

Throws: Error if connection fails

Example:

await sdk.connect();

disconnect(): Promise<void>

Disconnect from the blockchain network.

Example:

await sdk.disconnect();

destroy(): Promise<void>

Destroy SDK instance and cleanup all resources. After calling, the instance should not be reused.

Example:

await sdk.destroy();

getConnectionInfo(): ConnectionInfo

Get current connection information.

Returns: ConnectionInfo object with connection details

Example:

const info = sdk.getConnectionInfo();
console.log("Endpoint:", info.endpoint);
console.log("Network:", info.network);
console.log("Connected:", info.isConnected);

getApi(): ApiPromise | null

Get the Polkadot API instance (Substrate only).

Returns: Polkadot ApiPromise instance or null

Throws: Error if called on EVM chain

Example:

const api = sdk.getApi();
const chain = await api?.rpc.system.chain();

getEvmProvider(): PublicClient | null

Get the viem public client instance (EVM only).

Returns: Viem PublicClient instance or null

Throws: Error if called on Substrate chain

Example:

const client = sdk.getEvmProvider();
const balance = await client?.getBalance({ address });
const blockNumber = await client?.getBlockNumber();

Builder Pattern Methods

withEndpoint(endpoint: string): SelendraSDK

Set the endpoint URL.

Example:

const sdk = new SelendraSDK()
  .withEndpoint("wss://rpc.selendra.org")
  .withNetwork(Network.Selendra)
  .withChainType(ChainType.Substrate);

await sdk.connect();

withNetwork(network: Network | string): SelendraSDK

Set the network.

withChainType(chainType: ChainType): SelendraSDK

Set the chain type.

withOptions(options: Partial<SDKConfig>): SelendraSDK

Set multiple configuration options at once.

Properties

connected: boolean (readonly)

Check if SDK is currently connected.

Example:

if (sdk.connected) {
  console.log("SDK is connected");
}

Events

The SDK extends EventEmitter and emits the following events:

• connecting - Emitted when connection starts
• connected - Emitted when successfully connected
• disconnected - Emitted when disconnected
• error - Emitted on errors (receives Error object)
• reconnecting - Emitted when attempting to reconnect (receives attempt number)

Example:

sdk.on("connecting", () => console.log("Connecting..."));
sdk.on("connected", () => console.log("Connected!"));
sdk.on("disconnected", () => console.log("Disconnected"));
sdk.on("error", (error) => console.error("Error:", error));
sdk.on("reconnecting", (attempt) =>
  console.log(`Reconnect attempt ${attempt}`)
);

Types

SDKConfig

interface SDKConfig {
  endpoint?: string; // WebSocket or HTTP endpoint URL
  network?: Network | string; // Network to connect to
  chainType?: ChainType; // Chain type (Substrate or EVM)
  timeout?: number; // Connection timeout in ms (default: 30000)
  retryAttempts?: number; // Retry attempts (default: 3)
  retryDelay?: number; // Delay between retries in ms (default: 1000)
  autoReconnect?: boolean; // Auto-reconnect on disconnect (default: true)
  debug?: boolean; // Enable debug logging (default: false)
}

ConnectionInfo

interface ConnectionInfo {
  endpoint: string;
  network: Network | string;
  chainType: ChainType;
  isConnected: boolean;
  isConnecting: boolean;
  connectedAt?: number; // Timestamp of connection
  latency?: number; // Connection latency in ms
}

ChainType

enum ChainType {
  Substrate = "substrate",
  EVM = "evm",
}

Network

enum Network {
  Selendra = "selendra",
  SelendraTestnet = "selendra-testnet",
  SelendraDevnet = "selendra-devnet",
  Custom = "custom",
}

Factory Functions

createSDK(config?: SDKConfig): SelendraSDK

Create a new SDK instance.

Example:

import { createSDK } from "@selendrajs/sdk";

const sdk = createSDK({
  endpoint: "wss://rpc.selendra.org",
  network: Network.Selendra,
});

createAndConnect(config?: SDKConfig): Promise<SelendraSDK>

Create and immediately connect an SDK instance.

Example:

import { createAndConnect } from "@selendrajs/sdk";

const sdk = await createAndConnect({
  endpoint: "wss://rpc.selendra.org",
});

// SDK is already connected
console.log(sdk.connected); // true

Advanced Usage

Auto-Reconnect

The SDK supports automatic reconnection when the connection is lost:

const sdk = new SelendraSDK({
  endpoint: "wss://rpc.selendra.org",
  autoReconnect: true, // Enable auto-reconnect
  retryAttempts: 5, // Try 5 times
  retryDelay: 2000, // Wait 2 seconds between attempts
});

sdk.on("reconnecting", (attempt) => {
  console.log(`Reconnection attempt ${attempt}`);
});

await sdk.connect();

Error Handling

const sdk = new SelendraSDK();

sdk.on("error", (error) => {
  console.error("SDK Error:", error.message);
  // Handle error appropriately
});

try {
  await sdk.connect();
} catch (error) {
  console.error("Connection failed:", error);
  // Handle connection failure
}

Debug Mode

Enable debug mode to see detailed logs:

const sdk = new SelendraSDK({
  debug: true, // Enable debug logging
});

await sdk.connect();
// Logs will be printed to console

Multiple Connections

You can create multiple SDK instances for different chains:

// Substrate connection
const substrateSdk = new SelendraSDK({
  endpoint: "wss://rpc.selendra.org",
  chainType: ChainType.Substrate,
});

// EVM connection
const evmSdk = new SelendraSDK({
  endpoint: "https://rpc-evm.selendra.org",
  chainType: ChainType.EVM,
});

await Promise.all([substrateSdk.connect(), evmSdk.connect()]);

// Use both connections...

await Promise.all([substrateSdk.disconnect(), evmSdk.disconnect()]);

Development

Build

npm run build

Type Checking

npm run lint

Clean

npm run clean

Requirements

• Node.js >= 16.0.0
• TypeScript >= 5.0.0

Dependencies

• @polkadot/api - Polkadot.js API for Substrate chains
• viem - Modern, lightweight Ethereum library for EVM chains
• wagmi - React hooks for Ethereum (optional, for React integration)
• @wagmi/core - Core wagmi functionality
• @tanstack/react-query - Async state management for React
• eventemitter3 - Event emitter

License

Apache-2.0

Support

• GitHub: https://github.com/selendra/selendra-sdk
• Issues: https://github.com/selendra/selendra-sdk/issues

Roadmap

This SDK provides comprehensive blockchain functionality:

• [x] Account management (viem accounts)
• [x] Balance queries (Substrate & EVM)
• [x] Transaction submission
• [x] Contract interactions (viem contract APIs)
• [x] Staking operations (30 pallets supported)
• [x] Governance features (Democracy, Council, Treasury)
• [x] Event subscriptions
• [x] React hooks (wagmi compatible)
• [x] Unified Accounts (Substrate ↔ EVM mapping)

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.