# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.1.0] - 2026-01-20

### Added
- Initial release of IoTeX Node.js SDK
- gRPC client with TLS support for IoTeX blockchain
- Complete account management (create, import, export, list)
- Keystore encryption with password protection
- HD Wallet support with BIP44 derivation (m/44'/304'/...)
- Cryptographic operations (signing, verification, hashing)
- Address conversion between IoTeX and Ethereum formats
- Blockchain queries (chain metadata, blocks, epochs, receipts)
- Node delegate queries (current delegates, epoch data)
- Staking operations framework (implementation incomplete)
- Comprehensive utility functions (conversion, validation, error handling)
- TypeScript type definitions for all APIs
- Example scripts for common operations
- Unit tests for core functionality
- Comprehensive README documentation

### Dependencies
- @grpc/grpc-js ^1.12.0 - Modern gRPC client
- @grpc/proto-loader ^0.7.13 - Protobuf loading
- @iotexproject/iotex-address-ts ^1.0.2 - Official address conversion
- ethers ^6.13.0 - Ethereum-compatible cryptography
- bip39 ^3.1.0 - Mnemonic support
- hdkey ^2.1.0 - HD wallet key derivation

### Known Limitations
- Staking operations (stake2) framework is in place but action building is incomplete
- Vote bucket queries need protobuf deserialization
- Smart contract interaction not implemented
- Browser support not yet available (Node.js only)

## [0.2.0] - 2026-01-21

### Added
- **Comprehensive Documentation** - All docs consolidated in docs/ folder (14 files, 60K+ words)
  - DOCUMENTATION_INDEX.md - Master index for easy navigation
  - API_COMPLETE_REFERENCE.md - Exhaustive API documentation (150+ methods)
  - ACCOUNT_MANAGEMENT.md - Complete account creation, keystore, and HD wallet guide
  - ADVANCED_QUERIES.md - Advanced query patterns, error handling, performance optimization
  - FEATURES_STATUS.md - Feature implementation status checklist
  - Plus 9 additional reference documents
- New example scripts: get-all-delegates.ts, get-delegates-by-epoch.ts
- Support for querying all registered candidates (not just block producers)
- Support for querying delegates by specific epoch
- Delegate names now properly fetched from staking protocol
- Complete documentation of all 150+ SDK methods
- 50+ code examples across all documentation
- Error handling patterns with retry logic
- Security best practices guide
- Performance optimization recommendations

### Improved
- Updated delegate.ts to fetch and cache candidate names
- Implemented protobuf encoding/decoding for staking data
- Enhanced getDelegates() with epoch and all-candidates support
- Better error messages and handling patterns

### Documentation
- 100% API coverage with examples
- Use-case based navigation ("I want to...")
- Multiple entry points for different user types
- Cross-references between documents
- Search-friendly structure

## [0.2.2] - 2026-01-21

### Added
- **Extended Delegate Information** - Complete CandidateV2 protobuf data now exposed
  - `ownerAddress` - The owner address of the delegate
  - `operatorAddress` - The operator address (same as `address`)
  - `rewardAddress` - Where block rewards are sent
  - `totalWeightedVotes` - Raw weighted votes from blockchain
  - `selfStakeBucketIdx` - Index of the self-staking bucket
  - `selfStakingTokens` - Amount of self-staked tokens
  - `id` - Candidate ID

### Improved
- Enhanced `parseCandidateV2()` to parse all 8 fields from CandidateV2 protobuf message
- Added `readVarint()` helper method for parsing uint64 fields
- Modified `getDelegates()` to fetch and include all candidate details from staking protocol
- Updated `Candidate` interface to match actual CandidateV2 structure

### Documentation
- Updated all documentation files with new delegate fields
- Enhanced examples to demonstrate new field usage
- Added DELEGATE_FIELDS_UPDATE.md with comprehensive change documentation

### Backwards Compatibility
- All new fields are optional - existing code continues to work unchanged
- Basic fields (address, name, votes, production, active, rank) remain the same

## [0.2.3] - 2026-01-26

### Added
- **Account Buckets Example** - New example script `account-with-buckets.ts`
  - Queries account balance and metadata
  - Fetches all voting buckets for an address
  - Displays detailed bucket information
  - Groups buckets by delegate
  - Shows combined liquid and staked balance overview
  - Run with `npm run example:account-buckets`

### Documentation
- **Clarified Weighted Votes vs Raw Staked IOTX**
  - `delegate.votes` contains **weighted votes** (includes lock duration multiplier)
  - `bucket.stakedAmount` contains **raw staked IOTX** (no multiplier)
  - To calculate **total raw staked IOTX** for a delegate, sum all bucket amounts:
    ```typescript
    const buckets = await sdk.blockchain.getBucketList({
      candidateName: 'delegateName',
      offset: 0,
      limit: 10000
    });
    const totalStakedIotx = buckets.reduce(
      (sum, bucket) => sum + parseFloat(bucket.stakedAmount),
      0
    );
    ```
  - Updated API_COMPLETE_REFERENCE.md with vote clarifications
  - Updated QUERY_GUIDE.md with bucket query examples
  - Updated README_QUERIES.md with staking bucket section
- Fixed VoteBucket type documentation to match actual implementation
- Added examples showing how to sum bucket amounts for total staked calculation

### Fixed
- Corrected static method calls in example scripts (`Account.toEthAddress()`, `Account.verify()`)

## [Unreleased]

### Planned
- Complete protobuf action building for staking operations
- Implement vote bucket deserialization improvements
- Add smart contract ABI encoding/decoding
- Support for contract deployment and execution
- Event parsing and streaming
- Browser compatibility with grpc-web
- Performance optimizations
- Write operation support (transfers, staking)