npm package: @orbis1/orbis1-sdk-node
Description: Complete Orbis SDK for Node.js with bundled RGB core and Gas-Free transfers
Author: Orbis Team
Latest version: 0.1.0

# orbis1-sdk-node

Orbis1 SDK for Node.js — A modular TypeScript SDK for RGB asset operations with Bitcoin, featuring gas-free transfers and watch tower monitoring.

## Features

- **🔐 RGB Wallet Operations** — Complete RGB asset lifecycle: issue, send, receive, and manage NIA, UDA, CFA, and IFA assets
- **⚡ Gas-Free Transfers** — Transfer RGB assets without holding BTC for mining fees via collaborative transaction signing
- **🗼 Watch Tower** — Monitor RGB invoices and receive notifications for incoming transfers
- **🏗️ Modular Architecture** — Enable only the features you need; each feature is independently configurable
- **📦 Bundled Package** — Everything you need in one package: core RGB functionality and all features
- **🔒 Type Safety** — Comprehensive TypeScript types with Zod schema validation for runtime safety

## Prerequisites

- **Node.js** >= 18.0.0

## Installation

```bash
npm install orbis1-sdk-node
# or
yarn add orbis1-sdk-node
```

## Usage

### Basic Setup

```typescript
import {
  Orbis1SDK,
  generateKeys,
  Environment,
  LogLevel,
} from 'orbis1-sdk-node';

// 1. Generate or restore keys
const keys = await generateKeys('TESTNET4');

// 2. Configure and create SDK instance
const sdk = new Orbis1SDK({
  apiKey: 'your-api-key',
  environment: Environment.TESTNET,
  wallet: {
    enabled: true,
    keys,
    supportedSchemas: ['NIA', 'UDA', 'CFA', 'IFA'],
  },
  features: {
    gasFree: { enabled: true },
    watchTower: { enabled: true },
  },
  logging: { level: LogLevel.INFO },
});

// 3. Initialize SDK (registers and boots all enabled features)
await sdk.initialize();

// 4. Get wallet and perform operations
const wallet = sdk.getWallet();
await wallet.goOnline('ssl://electrum.example.com:50053');
await wallet.sync();

const balance = await wallet.getBtcBalance();
const assets = await wallet.listAssets(['NIA', 'CFA']);
```

### Gas-Free Transfers

Transfer RGB assets without holding BTC for mining fees:

```typescript
// 1. Request fee quote
const quote = await sdk.gasFree().requestFeeQuote({
  assetId: 'rgb:...',
  amount: 1000,
  recipientInvoice: 'rgb:invoice...',
});

console.log(`Service fee: ${quote.serviceFeeAmount} (asset units)`);
console.log(`Quote expires: ${quote.expiresAt}`);

// 2. Confirm transfer (if user accepts quote)
const result = await sdk.gasFree().confirmTransfer(request, quote);

console.log(`Transfer complete! TXID: ${result.txid}`);
console.log(`Mining fee paid by: ${result.minerFeePaidBy}`);
```

### Watch Tower Monitoring

Monitor RGB invoices for incoming transfers:

```typescript
// Add invoice to watch tower
await sdk.watchTower().addToWatchTower({
  invoice: 'rgb:invoice...',
});
```

### Cleanup

Always cleanup when done:

```typescript
await sdk.cleanup();
```

## Project Structure

```
orbis1-sdk-node/
├── src/                        # TypeScript source
│   ├── index.tsx               # Public API exports
│   ├── Orbis1SDK.ts            # Main SDK class, feature orchestration
│   │
│   ├── core/                   # RGB core functionality
│   │   ├── Interfaces.ts       # Types, enums (BitcoinNetwork, Keys, Assets, etc.)
│   │   ├── KeyManager.ts       # generateKeys, restoreKeys, decodeInvoice
│   │   ├── NativeRgb.ts        # RGB library bindings
│   │   ├── RgbError.ts         # RGB-specific error types
│   │   └── Wallet.ts           # Wallet class (RGB operations, transfers, UTXOs)
│   │
│   ├── types/                  # SDK configuration and types
│   │   ├── SDKConfig.ts        # SDKConfig interface, Environment, LogLevel, Zod schemas
│   │   ├── IFeatureModule.ts   # Feature module interface (lifecycle hooks)
│   │   └── Feature.ts          # Feature enum (GAS_FREE, WATCH_TOWER)
│   │
│   ├── errors/                 # Error handling
│   │   ├── OrbisError.ts       # Base SDK error class
│   │   ├── ConfigurationError.ts
│   │   └── FeatureNotEnabledError.ts
│   │
│   ├── features/               # Feature modules
│   │   ├── gas-free/
│   │   │   ├── GasFreeModule.ts # Main gas-free orchestration
│   │   │   ├── client/
│   │   │   │   ├── IServiceClient.ts
│   │   │   │   └── ServiceClient.ts # HTTP client for gas-free service
│   │   │   ├── consignment/
│   │   │   │   ├── IConsignmentReader.ts
│   │   │   │   └── ConsignmentReader.ts # RGB consignment file reader
│   │   │   ├── errors/
│   │   │   │   ├── GasFreeError.ts
│   │   │   │   ├── ConsignmentVerificationError.ts
│   │   │   │   ├── InvalidPSBTError.ts
│   │   │   │   ├── QuoteExpiredError.ts
│   │   │   │   └── ServiceUnavailableError.ts
│   │   │   ├── types/
│   │   │   │   ├── GasFreeConfig.ts
│   │   │   │   ├── GasFreeRequest.ts
│   │   │   │   ├── GasFreeResult.ts
│   │   │   │   └── FeeQuote.ts
│   │   │   └── utils/
│   │   │       ├── retry.ts
│   │   │       └── validation.ts
│   │   │
│   │   └── watch-tower/
│   │       ├── WatchTowerModule.ts # Watch tower feature implementation
│   │       └── types/
│   │           ├── WatchTowerConfig.ts
│   │           └── index.ts
│   │
│   └── utils/                  # Shared utilities
│       ├── FeatureRegistry.ts  # Feature registration and lifecycle management
│       └── logger.ts           # Logging utilities
│
├── dist/                       # Build output (compiled JavaScript + types)
├── package.json                # Package manifest and dependencies
├── tsconfig.json               # TypeScript configuration
├── jest.config.js              # Jest test configuration
└── README.md
```

## Architecture Overview

| Component | Purpose |
|-----------|---------|
| **Orbis1SDK** | Main SDK class; orchestrates features, manages lifecycle, provides unified API |
| **Wallet** | RGB wallet operations (issue assets, send/receive, UTXO management, sync) |
| **GasFreeModule** | Coordinates gas-free transfers via external mining inputs and service co-signing |
| **WatchTowerModule** | Monitors RGB invoices and integrates with notifications |
| **FeatureRegistry** | Manages feature lifecycle (register, initialize, cleanup) |
| **RGB Core** | Native RGB library bindings for Node.js |

### Key Design Principles

1. **Modular Features** — Features are optional and independently configurable; enable only what you need
2. **Explicit Initialization** — Call `sdk.initialize()` before using any features; lifecycle is clear and predictable
3. **Wallet Ownership** — Consumers control wallet lifecycle (goOnline, sync, close); SDK never calls these automatically
4. **Type Safety** — Comprehensive TypeScript types with Zod schema validation for runtime safety
5. **Error Handling** — Structured error hierarchy (OrbisError → ConfigurationError, FeatureNotEnabledError, GasFreeError, etc.)

## API Reference

### Core Classes

#### `Orbis1SDK`
Main SDK entry point. Manages features and provides unified API.

**Constructor:**
```typescript
new Orbis1SDK(config: SDKConfig)
```

**Methods:**
- `initialize(): Promise<void>` — Initialize SDK and all enabled features
- `cleanup(): Promise<void>` — Cleanup resources
- `getWallet(): Wallet | undefined` — Get wallet instance
- `gasFree(): GasFreeModule` — Access gas-free feature
- `watchTower(): WatchTowerModule` — Access watch tower feature
- `hasFeature(feature: Feature): boolean` — Check if feature is enabled
- `getConfig(): Readonly<SDKConfig>` — Get SDK configuration
- `getStatus()` — Get SDK and feature status

#### `Wallet`
RGB wallet for asset operations.

**Key Methods:**
- `goOnline(indexerUrl: string): Promise<void>` — Connect to electrum indexer
- `sync(): Promise<void>` — Sync wallet with blockchain
- `getBtcBalance(): Promise<BtcBalance>` — Get BTC balance
- `listAssets(schemas: AssetSchema[]): Promise<Assets>` — List RGB assets
- `blindReceive(...)` — Generate blinded UTXO invoice
- `witnessReceive(...)` — Generate witness transaction invoice
- `send(...)` — Send RGB assets
- `issueAssetNia(...)` — Issue NIA asset
- `issueAssetUda(...)` — Issue UDA asset
- `issueAssetCfa(...)` — Issue CFA asset
- `close(): Promise<void>` — Close wallet

### Feature Modules

#### `GasFreeModule`
Gas-free transfer feature.

**Methods:**
- `requestFeeQuote(request: GasFreeTransferRequest): Promise<FeeQuote>` — Request fee quote
- `confirmTransfer(request: GasFreeTransferRequest, quote: FeeQuote): Promise<GasFreeTransferResult>` — Execute transfer
- `getState()` — Get current transfer state

#### `WatchTowerModule`
Watch tower monitoring feature.

**Methods:**
- `addToWatchTower(params: { invoice: string }): Promise<void>` — Add invoice to watch tower

### Utility Functions

#### Key Management
```typescript
generateKeys(network: BitcoinNetwork): Promise<Keys>
restoreKeys(network: BitcoinNetwork, mnemonic: string): Promise<Keys>
decodeInvoice(invoice: string): Promise<InvoiceData>
```

## Examples

Complete working examples are available in the `example/` directory:

```bash
# Generate recipient invoice
yarn example:recipient

# Issue RGB asset and send via gas-free transfer
yarn example:user

# Send to specific recipient
yarn example:user <assetId> <recipientInvoice>
```

See [example/README.md](example/README.md) for detailed workflow documentation.

## Development

### Setup

```bash
# Clone repository
git clone <repo-url>
cd orbis1-sdk-node

# Install dependencies
yarn install

# Build the SDK
yarn build
```

### Scripts

| Command | Description |
|---------|-------------|
| `yarn build` | Compile TypeScript to JavaScript |
| `yarn test` | Run unit tests |
| `yarn test:watch` | Run tests in watch mode |
| `yarn test:coverage` | Run tests with coverage report |
| `yarn lint` | Check code style |
| `yarn lint:fix` | Fix linting issues |
| `yarn format` | Format code with Prettier |
| `yarn typecheck` | TypeScript type checking |

### Testing

```bash
# Run all tests
yarn test

# Run with coverage
yarn test:coverage

# Watch mode for development
yarn test:watch
```

## Environment Configuration

The SDK requires proper API key configuration based on environment:

- **Testnet**: Use API keys with prefix `pk_test`
- **Mainnet**: Use API keys with prefix `sk_live`

The SDK validates API key prefixes against the environment to prevent configuration errors.

## Error Handling

The SDK uses a structured error hierarchy:

```typescript
try {
  const result = await sdk.gasFree().confirmTransfer(request, quote);
} catch (error) {
  if (error instanceof GasFreeError) {
    console.error('Gas-free error:', error.code, error.message);
  } else if (error instanceof FeatureNotEnabledError) {
    console.error('Feature not enabled:', error.message);
  } else if (error instanceof ConfigurationError) {
    console.error('Configuration error:', error.message);
  } else {
    console.error('Unknown error:', error);
  }
}
```

## Requirements

- Node.js >= 18.0.0
- TypeScript >= 5.0.0 (if using TypeScript in your project)

## License

MIT

## Contributing

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

## Support

For issues and questions:
- GitHub Issues: [Report a bug](https://github.com/orbis/orbis1-sdk-node/issues)
- Documentation: [API Reference](#api-reference)

---

**Version:** 0.1.0  
**Last Updated:** March 10, 2026