npm package: @pioneer-platform/maya-network
Description: MayaChain network integration using ShapeShift Unchained API.
Latest version: 8.20.10

# MayaChain Network Module

MayaChain network integration using ShapeShift Unchained API.

## Architecture

This module has been migrated from direct MayaChain node calls to use the Unchained API for better reliability and reduced node connection errors.

### API Endpoints

**Primary: ShapeShift Unchained API**
- Base URL: `https://api.mayachain.shapeshift.com`
- Documentation: https://api.mayachain.shapeshift.com/swagger
- Provides: Account info, balances, transaction history, broadcasting

**Fallback: Midgard API**
- Base URL: `https://midgard.mayachain.info/v2`
- Provides: Pool data, aggregated chain statistics
- Used for: Pool queries not available in Unchained

## Features

### ✅ Implemented via Unchained
- `getInfo()` - Network information
- `getAccount(address)` - Account details with balances
- `getBalance(address)` - Single CACAO balance
- `getBalances(address)` - All asset balances
- `txs(address, cursor, pageSize)` - Paginated transaction history
- `broadcast(rawTx)` - Transaction broadcasting

### ✅ Implemented via Midgard
- `getPools()` - All liquidity pools
- `getPool(poolId)` - Specific pool details

### ⚠️ Not Available in Unchained
- `getTransaction(txid)` - Direct tx lookup (use account txs instead)
- `getPoolAddress()` - Inbound addresses (requires node access)

## Usage

```javascript
const network = require('@pioneer-platform/mayachain-network')

// Get network info
const info = await network.info()

// Get account balances
const balances = await network.getBalances('maya1...')

// Get transaction history (paginated)
const txs = await network.txs('maya1...', undefined, 50)

// Broadcast transaction
const result = await network.broadcast(signedTxBase64)
```

## Balance Formats

The module returns balances in standardized format:

```javascript
[
  {
    denom: 'cacao',          // Asset denomination
    amountBase: '25029714637', // Raw amount (base units)
    amount: 25.029714637,    // Decimal amount
    decimals: 10             // Decimal places
  },
  {
    denom: 'maya',
    amountBase: '4104',
    amount: 0.4104,
    decimals: 4
  }
]
```

### Decimal Places
- **CACAO**: 10 decimals (1 CACAO = 10,000,000,000 base units)
- **MAYA**: 4 decimals (1 MAYA = 10,000 base units)

## Error Handling

The module uses minimal logging with retry logic:
- 2 retries on 503 errors with exponential backoff
- Logs only errors and key operations (no verbose stack traces)
- Returns structured error responses for broadcast failures

## Migration Notes

### Changes from Previous Version
1. ✅ Removed direct node calls to `mayanode.mayachain.info`
2. ✅ Removed verbose error logging (no more giant stack traces)
3. ✅ Uses Unchained API for account/balance/tx operations
4. ✅ Keeps Midgard for pool data (not in Unchained)
5. ✅ Simplified retry logic with minimal logging

### Benefits
- **Reliability**: Unchained API is more stable than direct node access
- **Performance**: Faster responses, better caching
- **Cleaner logs**: No more 503 spam in logs
- **Maintainability**: Single API contract vs multiple node endpoints

## Testing

```bash
cd modules/coins/mayachain/mayachain-network
bun run test
```

Test coverage:
- ✅ Network info retrieval
- ✅ Account balance queries
- ✅ Multi-asset balance parsing
- ✅ Transaction history (paginated)
- ✅ Pool data from Midgard
- 💬 Broadcasting (commented out - needs real signed tx)

## Development

```bash
# Build
bun run build

# Test
bun run test

# Install dependencies
bun install
```

## Dependencies

- `axios` - HTTP client
- `axios-retry` - Retry logic for 503 errors
- `@pioneer-platform/loggerdog` - Logging

## License

MIT