OpenLedger Node SDK

A comprehensive TypeScript SDK for interacting with OpenLedger blockchain networks. Provides seamless integration with smart contracts for staking, data networks, governance, AI models, and token operations.

Features

• 🔐 Wallet Integration - Ethereum wallet support with transaction signing
• 📡 WebSocket Communication - Real-time messaging with signature verification
• ⛽ Gas Optimization - EIP-1559 support with dynamic gas estimation
• 🏗️ Modular Architecture - Optional module initialization based on contract addresses
• 🔒 Type Safety - Full TypeScript support with comprehensive type definitions
• 📊 Multi-Contract Support - Staking, governance, data networks, and more
• 🚀 Production Ready - Comprehensive error handling and transaction management

Installation

npm install openledger-sdk

Requirements

• Node.js >= 18.0.0
• npm >= 8.0.0

Quick Start

Basic Setup (Read-Only Operations)

For read-only operations, no private key is required:

import OpenLedgerSDK from 'openledger-sdk';

const sdk = new OpenLedgerSDK({
  rpcUrl: 'https://your-rpc-endpoint.com',
  url: 'wss://your-websocket-endpoint.com',
  authToken: 'your-auth-token',
  // Contract addresses (optional)
  stakeAddress: '0x...',
  datanetAddress: '0x...'
});

// Read operations work without a private key
const stakeInfo = await sdk.stake.getConfig();
const datanetInfo = await sdk.getDataNetInfo('0x...');

Full Setup (Read + Write Operations)

For write operations (transactions), provide a private key:

import OpenLedgerSDK from 'openledger-sdk';

const sdk = new OpenLedgerSDK({
  rpcUrl: 'https://your-rpc-endpoint.com',
  url: 'wss://your-websocket-endpoint.com',
  authToken: 'your-auth-token',
  privateKey: 'your-ethereum-private-key', // Required for write operations
  stakeAddress: '0x...',
  datanetAddress: '0x...',
  governanceAddress: '0x...',
  // ... other contract addresses
});

// Now you can perform write operations
await sdk.stake.stake('1000', { gasLimit: '300000' });
await sdk.sendNativeBalance('0x...', '0.1');

Configuration

The SDK accepts an OpenLedgerConfig object with the following properties:

| Property | Type | Required | Description | |----------|------|----------|-------------| | rpcUrl | string | ✅ | Ethereum RPC endpoint | | url | string | ✅ | WebSocket server URL | | authToken | string | ✅ | Authentication token | | privateKey | string | ⚠️ | Private key (required for write operations) | | stakeAddress | string | ❌ | Stake contract address | | datanetAddress | string | ❌ | DataNet contract address | | governanceAddress | string | ❌ | Governance contract address | | modelAddress | string | ❌ | Model contract address | | wopnAddress | string | ❌ | WOpn token contract address | | creditManagerAddress | string | ❌ | Credit Manager contract address | | tokenAddress | string | ❌ | Token contract address | | modelProposalAddress | string | ❌ | Model Proposal contract address |

When Do You Need a Private Key?

✅ No Private Key Required (Read Operations)

• Checking balances and contract states
• Reading configuration data
• Fetching transaction receipts
• Getting user acknowledgment status
• All get* and is* methods

🔐 Private Key Required (Write Operations)

• Sending transactions
• Staking and unstaking tokens
• Creating governance proposals
• Submitting data to networks
• WebSocket operations (register, sendMessage, uploadData)
• All methods that modify blockchain state

Available Modules

Each module is automatically initialized if its contract address is provided:

Stake Module

await sdk.stake.stake('1000');
await sdk.stake.requestUnstake('500');
const config = await sdk.stake.getConfig(); // Read-only

DataNet Module

await sdk.datanet.storeDataPoint(id, hash, signature);
const info = await sdk.getDataNetInfo(address); // Read-only

Governance Module

await sdk.governance.createProposal(description);
await sdk.governance.vote(proposalId, support);

Token Operations

await sdk.wopn.transfer(recipient, amount);
const balance = await sdk.wopn.balanceOf(address); // Read-only

WebSocket Communication

// Connect and register (requires private key)
await sdk.connect();
const workerId = await sdk.register();

// Send messages (requires private key)
await sdk.sendMessage({ type: 'chat', content: 'Hello' });

// Upload data (requires private key)  
await sdk.uploadData('msg-id', { data: 'example' });

// Clean up
await sdk.close();

Gas Management

The SDK provides sophisticated gas optimization:

// Custom gas parameters
const gasOptions = {
  gasLimit: '500000',
  maxFeePerGas: '20000000000', // 20 gwei
  maxPriorityFeePerGas: '2000000000' // 2 gwei
};

await sdk.stake.stake('1000', gasOptions);

Error Handling

try {
  await sdk.stake.stake('1000');
} catch (error) {
  if (error.message.includes('Insufficient balance')) {
    console.log('Not enough tokens to stake');
  } else if (error.message.includes('Wallet not initialized')) {
    console.log('Private key required for this operation');
  }
}

Development

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Run tests in watch mode  
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Create package
npm run pack

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass: npm test
6. Build the project: npm run build
7. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Documentation: OpenLedger Docs
• Issues: GitHub Issues
• Community: Discord