@cfxdevkit/confluxscan-espace

A TypeScript library for interacting with Conflux eSpace Scanner API.

Installation

npm install @cfxdevkit/confluxscan-espace
Copy

Features

• Full TypeScript support with comprehensive type definitions
• Complete Conflux eSpace Scanner API coverage
• Comprehensive data formatting utilities
• Built-in error handling and address validation
• Detailed documentation and examples
• Jest-based test suite with high coverage
• ESLint and Prettier for code quality
• Husky for git hooks

Project Structure

src/
├── core/                 # Core API implementation
│   ├── api.ts           # Base API class for HTTP requests
│   ├── scanner.ts       # Main scanner implementation
│   └── modules/         # API module implementations
│       ├── account.ts   # Account-related operations
│       ├── contract.ts  # Smart contract operations
│       ├── nft.ts       # NFT-related operations
│       ├── statistics.ts # Network statistics
│       └── token.ts     # Token operations
├── formatters/          # Data formatting utilities
│   ├── dates.ts        # Date and timestamp formatting
│   ├── numbers.ts      # Numeric and unit formatting
│   └── responses.ts    # API response formatting
├── wrapper/            # High-level wrapper with formatting
│   ├── base.ts        # Base wrapper functionality
│   ├── scanner.ts     # Main scanner wrapper
│   └── modules/       # Formatted module implementations
├── types/             # TypeScript type definitions
│   └── domains/       # Domain-specific types
└── utils/             # Utility functions
    ├── logger.ts      # Logging configuration
    └── validation.ts  # Address validation
Copy

Core Modules

Account Module

• Balance queries (single/multi-address)
• Transaction history
• Token transfer history
• NFT transfer tracking
• Mining history
• Balance history

Contract Module

• ABI retrieval
• Source code access
• Contract verification
• Proxy contract support

NFT Module

• NFT balances
• Token metadata
• Transfer history
• Ownership tracking

Statistics Module

• Network metrics
• Account activity
• Transaction analytics
• Token statistics
• Gas usage metrics
• Mining statistics

Token Module

• Token balances
• Supply information
• Transfer history
• Historical data

Formatters

Date Formatter

import { DateFormatter } from "@cfxdevkit/confluxscan-espace";

// Format timestamps
DateFormatter.formatDate(1707307200, "full"); // "2024-02-07 12:00:00"
DateFormatter.formatDate(1707307200, "date"); // "2024-02-07"

// Get relative timestamps
DateFormatter.get24HoursAgo(); // timestamp from 24 hours ago
DateFormatter.getTimeAgo(7); // timestamp from 7 days ago
Copy

Number Formatter

import { NumberFormatter } from "@cfxdevkit/confluxscan-espace";

// Format numbers
NumberFormatter.formatNumber(1234.5678); // "1,234.5678"
NumberFormatter.formatPercentage(50.5678); // "50.57%"

// Format blockchain values
NumberFormatter.formatGas("1000000000"); // "1.0 Gdrip"
NumberFormatter.formatCFX("1000000000000000000"); // "1 CFX"
Copy

Utilities

Address Validation

import { AddressValidator } from "@cfxdevkit/confluxscan-espace";

// Validate single address
AddressValidator.validateAddress("0x1234..."); // true/false

// Validate multiple addresses
AddressValidator.validateAddresses(["0x1234...", "0x5678..."]); // true/false
Copy

Logging

import { createLogger } from "@cfxdevkit/confluxscan-espace";

// Create module-specific logger
const logger = createLogger("MyModule");
logger.info("Operation successful");
logger.error({ error }, "Operation failed");
Copy

Usage

Basic Setup

import { ESpaceScanner, ESpaceScannerWrapper } from "@cfxdevkit/confluxscan-espace";

// Initialize scanner for different networks
const mainnetScanner = new ESpaceScannerWrapper({ target: "mainnet" });
const testnetScanner = new ESpaceScannerWrapper({ target: "testnet" });

// With API key for higher rate limits
const scannerWithApiKey = new ESpaceScannerWrapper({
    target: "mainnet",
    apiKey: "YOUR_API_KEY" // optional
});
Copy

Account Operations

// Get account balance
const balance = await scanner.account.getBalance({
    address: "0x1234...",
    tag: "latest"
});

// Get transaction history
const transactions = await scanner.account.getTransactionList({
    address: "0x1234...",
    startblock: 1000000,
    endblock: 2000000,
    page: 1,
    offset: 10
});

// Get token transfers
const transfers = await scanner.account.getTokenTransfers({
    address: "0x1234...",
    contractaddress: "0x5678..." // optional
});
Copy

Contract Operations

// Get contract ABI
const abi = await scanner.contract.getABI({
    address: "0x1234..."
});

// Get contract source code
const source = await scanner.contract.getSourceCode({
    address: "0x1234..."
});

// Verify proxy contract
const verification = await scanner.contract.verifyProxyContract({
    address: "0x1234...",
    expectedimplementation: "0x5678..."
});
Copy

NFT Operations

// Get NFT balances
const balances = await scanner.nft.getBalances({
    owner: "0x1234..."
});

// Get NFT transfers
const transfers = await scanner.nft.getTransfers({
    contract: "0x1234...",
    tokenId: "1"
});

// Get NFT metadata
const metadata = await scanner.nft.getPreview({
    contract: "0x1234...",
    tokenId: "1",
    withMetadata: true
});
Copy

Statistics Operations

// Get network statistics
const supply = await scanner.statistics.getSupply();

// Get mining statistics
const mining = await scanner.statistics.getMining({
    intervalType: "day",
    minTimestamp: 1234567890,
    maxTimestamp: 2345678901
});

// Get top accounts
const topSenders = await scanner.statistics.getTopTransactionSender({
    spanType: "24h"
});
Copy

Token Operations

// Get token balance
const balance = await scanner.token.getTokenBalance({
    address: "0x1234...",
    contractaddress: "0x5678..."
});

// Get token supply
const supply = await scanner.token.getTokenSupply({
    contractaddress: "0x1234..."
});

// Get historical data
const history = await scanner.token.getTokenSupplyHistory({
    contractaddress: "0x1234...",
    blockno: 1000000
});
Copy

Development

Requirements:

• Node.js >= 16.0.0
• npm or yarn

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Generate documentation
npm run docs

# Lint and format code
npm run lint
npm run format
Copy

Documentation

API documentation is generated using TypeDoc and is available in the docs directory:

npm run docs
Copy

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• GitHub Repository
• Issue Tracker
• Documentation

Support

For support, please:

1. Check the documentation
2. Search existing issues
3. Open a new issue if needed