Skip to main content

Configuration and Integration

The Standards SDK provides flexible configuration options to integrate with various Hedera infrastructure providers and customize behavior for your specific needs.

Mirror Node Configuration​

The SDK supports integration with custom mirror node providers beyond the default Hedera public mirror nodes. This enables enhanced performance, reliability, and access to specialized features.

Default & Custom Providers​

Mirror Node Setup

Default

1import { HederaMirrorNode } from '@hashgraphonline/standards-sdk';
2

3// Uses public Hedera mirror nodes
4const mirrorNode = new HederaMirrorNode('mainnet', logger);
5// Mainnet: https://mainnet-public.mirrornode.hedera.com
6// Testnet: https://testnet.mirrornode.hedera.com

Configuration Options​

The MirrorNodeConfig interface supports:

interface MirrorNodeConfig {
  /** Custom mirror node URL. Can include <API-KEY> placeholder for URL-based API keys */
  customUrl?: string;
  
  /** API key for authentication. Used in both Authorization header and URL replacement */
  apiKey?: string;
  
  /** Additional custom headers to include with requests */
  headers?: Record<string, string>;
}

Dynamic Configuration Updates​

Runtime Configuration

Dynamic Switching

1const mirrorNode = new HederaMirrorNode('mainnet', logger);
2

3// Switch to high-performance provider during peak usage
4function switchToHighPerformanceMode() {
5mirrorNode.configureMirrorNode({
6  customUrl: 'https://premium-mirror.example.com/api',
7  apiKey: process.env.PREMIUM_API_KEY,
8  headers: {
9    'X-Priority': 'high'
10  }
11});
12}
13

14// Revert to standard configuration
15function switchToStandardMode() {
16mirrorNode.configureMirrorNode({
17  customUrl: undefined, // Reverts to default Hedera mirror nodes
18  apiKey: undefined,
19  headers: {}
20});
21}

Retry Configuration​

Customize retry behavior for network requests to handle transient failures:

Retry Logic

Retry Strategy

1// Configure retry settings
2mirrorNode.configureRetry({
3maxRetries: 5,              // Maximum number of retry attempts
4initialDelayMs: 500,        // Initial delay between retries
5maxDelayMs: 30000,          // Maximum delay between retries
6backoffFactor: 2            // Exponential backoff multiplier
7});

Retry Strategy​

The SDK implements intelligent retry logic:

  • Automatic Retries: For network errors and 5xx server errors
  • No Retry: For client errors (4xx) except rate limiting (429)
  • Exponential Backoff: Delays increase exponentially with each retry
  • Maximum Delay Cap: Prevents excessive wait times

Integration with HCS Protocols​

Custom Mirror Nodes with Inscriptions & HCS-10​

Protocol Integration

HCS-1 Inscription

1import { inscribe } from '@hashgraphonline/standards-sdk';
2

3// Configure custom mirror node for inscriptions
4const customConfig = {
5network: 'mainnet',
6mirrorNodeConfig: {
7  customUrl: 'https://fast-mirror.example.com',
8  apiKey: process.env.MIRROR_API_KEY
9}
10};
11

12const result = await inscribe(
13{
14  type: 'text',
15  content: 'High-performance inscription',
16  fileName: 'data.txt'
17},
18{
19  ...customConfig,
20  accountId: '0.0.123456',
21  privateKey: 'your-private-key'
22}
23);

Environment-Based Configuration​

Implement environment-aware configuration:

Environment Setup

Env Aware Factory

1import { HederaMirrorNode, Logger } from '@hashgraphonline/standards-sdk';
2

3function createMirrorNode(network: 'mainnet' | 'testnet'): HederaMirrorNode {
4const logger = new Logger({ 
5  module: 'MirrorNode',
6  level: process.env.LOG_LEVEL || 'info'
7});
8

9// Development environment
10if (process.env.NODE_ENV === 'development') {
11  return new HederaMirrorNode(network, logger);
12}
13

14// Production environment with custom provider
15if (process.env.NODE_ENV === 'production') {
16  return new HederaMirrorNode(network, logger, {
17    customUrl: process.env.MIRROR_NODE_URL,
18    apiKey: process.env.MIRROR_NODE_API_KEY,
19    headers: {
20      'X-Environment': 'production',
21      'X-Application': process.env.APP_NAME || 'standards-sdk-app'
22    }
23  });
24}
25

26// Test environment with mocked responses
27if (process.env.NODE_ENV === 'test') {
28  return new HederaMirrorNode(network, logger, {
29    customUrl: 'http://localhost:3000/mock-mirror',
30    headers: {
31      'X-Test-Mode': 'true'
32    }
33  });
34}
35

36return new HederaMirrorNode(network, logger);
37}

Performance Optimization​

Connection Pooling & Batching​

Optimization

Connection Pool

1// Create a pool of mirror node instances
2class MirrorNodePool {
3private pool: HederaMirrorNode[] = [];
4private currentIndex = 0;
5

6constructor(size: number, network: 'mainnet' | 'testnet', config: MirrorNodeConfig) {
7  for (let i = 0; i < size; i++) {
8    this.pool.push(new HederaMirrorNode(network, logger, config));
9  }
10}
11

12getNext(): HederaMirrorNode {
13  const node = this.pool[this.currentIndex];
14  this.currentIndex = (this.currentIndex + 1) % this.pool.length;
15  return node;
16}
17}
18

19// Use the pool for load distribution
20const mirrorPool = new MirrorNodePool(5, 'mainnet', {
21customUrl: 'https://load-balanced-mirror.com',
22apiKey: process.env.API_KEY
23});
24

25// Get next available mirror node instance
26const mirrorNode = mirrorPool.getNext();

Security Considerations​

API Key Management & Secure Headers​

Security

API Managing

1// Never hardcode API keys
2const UNSAFE = { apiKey: 'sk_live_abc123...' }; // ❌ Never do this
3

4// Use environment variables
5const SAFE = { apiKey: process.env.MIRROR_NODE_API_KEY }; // ✅ Load from environment
6

7// Validate API key presence
8if (!process.env.MIRROR_NODE_API_KEY) {
9throw new Error('MIRROR_NODE_API_KEY environment variable is required');
10}

Monitoring and Debugging​

Monitoring

Request Logging

1const logger = new Logger({
2module: 'MirrorNode',
3level: 'debug', // Enable debug logs
4callback: (level, message, meta) => {
5  if (meta?.url) {
6    console.log(`Mirror Node Request: ${meta.url}`);
7  }
8}
9});
10

11const mirrorNode = new HederaMirrorNode('testnet', logger, {
12customUrl: process.env.DEBUG_MIRROR_URL
13});

Next Steps​