# IoTeX SDK - Quick Reference

## Installation & Setup

```bash
cd /Users/simone/Source/GitHub/simonerom/ioctl/iotex-node-sdk
npm install
npm run build
```

## Basic Usage

```typescript
import { IoTeXSDK } from 'iotex-node-sdk';

const sdk = IoTeXSDK.mainnet();
await sdk.connect();

// Your queries here

sdk.disconnect();
```

## Quick API Reference

### Chain Stats
```typescript
// Get chain metadata
const chainMeta = await sdk.blockchain.getChainMeta();
console.log(`Height: ${chainMeta.height}`);
console.log(`Epoch: ${chainMeta.epoch.num}`);
console.log(`TPS: ${chainMeta.tpsFloat}`);

// Get latest block
const block = await sdk.blockchain.getBlock(Number(chainMeta.height));

// Get node version
const version = await sdk.blockchain.getVersion();
```

### Delegates
```typescript
// Get current delegates (top 36) with full information
const delegates = await sdk.node.getDelegates();
delegates.forEach(d => {
  console.log(`${d.rank}. ${d.name} (${d.operatorAddress})`);
  console.log(`   Votes: ${d.votes} IOTX, Production: ${d.production} blocks`);
  console.log(`   Owner: ${d.ownerAddress}, Reward: ${d.rewardAddress}`);
});

// Get all delegates (all registered candidates)
const all = await sdk.node.getDelegates({ all: true });

// Get delegates for specific epoch
const epoch1000 = await sdk.node.getDelegates({ epochNumber: 1000 });

// Access extended delegate information
const topDelegate = delegates[0];
console.log('Owner Address:', topDelegate.ownerAddress);
console.log('Operator Address:', topDelegate.operatorAddress);
console.log('Reward Address:', topDelegate.rewardAddress);
console.log('Self-staking Tokens:', topDelegate.selfStakingTokens);

// Get current epoch
const epoch = await sdk.node.getCurrentEpoch();
```

### Account Info
```typescript
// Get balance
const balance = await sdk.account.getBalance('io1...');
console.log(`Balance: ${balance} IOTX`);

// Get full metadata
const meta = await sdk.account.getMeta('io1...');
console.log(`Nonce: ${meta.nonce}`);
console.log(`Actions: ${meta.numActions}`);

// Works with Ethereum addresses too
const balance2 = await sdk.account.getBalance('0x...');
```

### Address Conversion
```typescript
import { toEthAddress, toIoAddress } from 'iotex-node-sdk';

const ethAddr = toEthAddress('io1jzdxuv7etyfvs7th7jwyspswr6y660zjd7lykg');
// 0x909a6e33d95912c87977f49c48060e1e89ad3c52

const ioAddr = toIoAddress('0x909a6e33d95912c87977f49c48060e1e89ad3c52');
// io1jzdxuv7etyfvs7th7jwyspswr6y660zjd7lykg
```

## Test Commands

```bash
# Run mainnet query tests
npx ts-node test-mainnet-queries.ts

# Run delegate tests
npx ts-node test-delegates.ts

# Run examples
npm run example:quick-start
npm run example:balance
npm run example:delegates
npm run example:blockchain
```

## Test Results Summary

### ✅ Working (Production Ready)
- Chain metadata ✅
- Block queries ✅
- Epoch information ✅
- Delegate list with votes ✅
- Blocks produced per delegate ✅
- Account balance ✅
- Account metadata (nonce, etc.) ✅
- Action history ✅
- Address conversion ✅
- Bucket information ✅ (manual protobuf encoding/decoding)

### 📋 Bucket Queries
```typescript
// Get buckets by voter
const buckets = await sdk.blockchain.getBucketList({
  voterAddress: 'io1jzdxuv7etyfvs7th7jwyspswr6y660zjd7lykg'
});

// Get buckets by candidate
const buckets = await sdk.blockchain.getBucketList({
  candidateName: 'iotexlab'
});

// Get all buckets (paginated)
const buckets = await sdk.blockchain.getBucketList({
  offset: 0,
  limit: 100
});

// Get specific bucket by index
const bucket = await sdk.blockchain.getBucket(32);
```

## Networks

```typescript
// Mainnet
const sdk = IoTeXSDK.mainnet();

// Testnet
const sdk = IoTeXSDK.testnet();

// Custom
const sdk = new IoTeXSDK({
  endpoint: 'your-node:443',
  secure: true
});
```

## Error Handling

```typescript
import { IoTeXError } from 'iotex-node-sdk';

try {
  const balance = await sdk.account.getBalance(address);
} catch (error) {
  if (error instanceof IoTeXError) {
    console.error(`Error ${error.code}: ${error.message}`);
  }
}
```

## Files

- `test-mainnet-queries.ts` - Comprehensive mainnet tests
- `test-delegates.ts` - Delegate query tests
- `TEST_RESULTS.md` - Detailed test results
- `QUERY_GUIDE.md` - Complete query API guide
- `README_QUERIES.md` - Query-focused documentation