@first-ledger/kit-adapter/README.md

A streamlined toolkit for querying and parsing blockchain network data, encompassing account details, transactions, and metadata, using nu-client with built-in caching for enhanced performance and access efficiency.

# First-Ledger Data Kit

The **Data Kit** is a modular, lightweight package designed to fetch, aggregate, and parse data from various blockchain networks. It provides developers with a unified interface to access blockchain data in a structured and usable format, enabling seamless integration into applications such as wallets, analytics tools, decentralized finance (DeFi) platforms, and more.

## Features

- **Multi-Chain Support**: Fetch data from popular blockchains like Ethereum, Bitcoin, Binance Smart Chain, Solana, and more.
- **Data Aggregation**: Combine raw blockchain data (e.g., transactions, blocks, smart contract events) into a cohesive format.
- **Custom Parsers**: Transform chain-specific data into standardized outputs tailored to your application's needs.
- **Extensible Design**: Easily add support for new blockchains or data types with modular adapters.
- **Real-Time & Historical Data**: Retrieve both live updates and archived blockchain data.
- **Error Handling**: Robust mechanisms to manage network issues, rate limits, and malformed data.

## Installation

Install the package via npm:

```bash
npm install @first-ledger/kit
```

Or with Yarn:

```bash
yarn add @first-ledger/kit
```

## Usage

### Basic Example

Fetch and parse the latest block data from Ethereum:

```javascript
const { BlockchainDataKit } = require('@first-ledger/kit');

// Initialize the kit with a blockchain adapter
const kit = new BlockchainDataKit({
  chain: 'ethereum',
  rpcUrl: 'https://mainnet.infura.io/v3/YOUR_INFURA_KEY',
});

// Fetch the latest block
kit
  .getLatestBlock()
  .then((block) => {
    console.log('Latest Ethereum Block:', block);
  })
  .catch((err) => {
    console.error('Error fetching block:', err);
  });
```

**Aggregating Transaction Data**

Aggregate transaction data for a specific address:

```jsx
const { BlockchainDataKit } = require('blockchain-data-kit');

const kit = new BlockchainDataKit({
  chain: 'bitcoin',
  rpcUrl: 'http://your-bitcoin-node:8332',
});

kit
  .getAddressTransactions('1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa')
  .then((transactions) => {
    console.log('Bitcoin Transactions:', transactions);
  })
  .catch((err) => {
    console.error('Error:', err);
  });
```

**Supported Blockchains**

| **Blockchain**      | **Adapter Name** | **Status** |
| ------------------- | ---------------- | ---------- |
| XRP Ledger          | xrpl             | Stable     |
| Ethereum            | ethereum         | TBD        |
| Bitcoin             | bitcoin          | TBD        |
| Binance Smart Chain | bsc              | TBD        |
| Solana              | solana           | TBD        |
| Polygon             | polygon          | TBD        |

To request support for additional chains, see Contributing (#contributing).

**Configuration**

The kit accepts a configuration object to customize its behavior:

javascript

```jsx
const kit = new BlockchainDataKit({
  chain: 'ethereum', // Blockchain adapter name
  rpcUrl: 'YOUR_RPC_URL', // RPC endpoint
  apiKey: 'YOUR_API_KEY', // Optional: API key if required
  timeout: 5000, // Request timeout in ms
  maxRetries: 3, // Retry failed requests
  parser: customParserFunction, // Optional: Custom parsing logic
});
```

**Custom Parsers**

You can define custom parsers to format data according to your needs:

javascript

```jsx
function customParserFunction(rawData) {
  return {
    blockNumber: rawData.number,
    timestamp: new Date(rawData.timestamp * 1000),
    transactionCount: rawData.transactions.length,
  };
}

const kit = new BlockchainDataKit({
  chain: 'ethereum',
  rpcUrl: 'YOUR_RPC_URL',
  parser: customParserFunction,
});

kit.getLatestBlock().then((parsedBlock) => {
  console.log('Custom Parsed Block:', parsedBlock);
});
```

**API Reference**

**BlockchainDataKit(config)**

- **config**: Object containing chain type, RPC URL, and optional settings.

**Methods**

- .getLatestBlock(): Fetches the most recent block.
- .getBlockByNumber(number): Fetches a block by its number or height.
- .getAddressTransactions(address): Retrieves transactions for a given address.
- .getContractEvents(contractAddress, eventName): Fetches smart contract events (if supported by the chain).

For detailed method documentation, see the API Docs (docs/api.md).

**Contributing**

We welcome contributions! To add a new blockchain adapter or improve the kit:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/your-feature).
3. Submit a pull request with your changes.

See CONTRIBUTING.md for more details.

**License**

This project is licensed under the MIT License. See LICENSE for details.

**Support**

For issues or questions, open a ticket on our [GitHub Issues page](https://github.com/first-ledger/kit/issues) or reach out via email at support@first-ledger.com.