Skip to content

Commit 4c4c99b

Browse files
Simon Sefcikclaude
authored and
Simon Sefcik
committed
feat: Add STRUCTURE.md documentation files for blockapi
- Add comprehensive STRUCTURE.md files across all blockapi directories - Document file organization, purpose, and relationships - Include detailed descriptions for test data, API implementations, and utilities - Provide navigation links between related documentation files 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 96280c1 commit 4c4c99b

16 files changed

Lines changed: 2278 additions & 0 deletions

File tree

‎STRUCTURE.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# Blockapi Library
2+
3+
## Overview
4+
5+
Blockapi is a comprehensive Python library that provides a unified interface for interacting with blockchain APIs, cryptocurrency data providers, and NFT marketplaces. As a critical component of the Crypkit platform, it abstracts the complexity of integrating with 50+ blockchain networks through both legacy (v1) and modern (v2) implementations, handling everything from simple balance queries to complex DeFi portfolio analysis and NFT data aggregation.
6+
7+
## Purpose and Architecture
8+
9+
The library serves as a blockchain data abstraction layer that:
10+
- Provides a consistent, unified API across diverse blockchain networks and data providers
11+
- Handles API authentication, rate limiting, retries, and error recovery automatically
12+
- Normalizes heterogeneous data formats from various sources into standardized models
13+
- Supports both basic blockchain operations (balance, transactions) and advanced features (DeFi protocols, NFT marketplaces)
14+
- Maintains backward compatibility through dual-version architecture (v1 legacy, v2 modern)
15+
16+
### Architectural Principles
17+
- **Dynamic API Discovery**: Automatically discovers and uses available APIs without hardcoding
18+
- **Graceful Degradation**: Falls back to alternative APIs when primary ones fail
19+
- **Precision First**: All monetary values use Decimal type for financial accuracy
20+
- **Extensibility**: New blockchains and protocols can be added by implementing standard interfaces
21+
22+
## Directory Structure
23+
24+
```
25+
blockapi/
26+
├── CHANGELOG.md # Detailed version history and changes
27+
├── LICENSE.md # MIT License
28+
├── Makefile # Build and test automation
29+
├── README.md # User-facing documentation
30+
├── pyproject.toml # Python project configuration (Black, isort, semantic-release)
31+
├── pytest.ini # Pytest configuration with custom markers
32+
├── setup.cfg # Package metadata (empty, uses setup.py)
33+
├── setup.py # Package installation and dependencies
34+
└── blockapi/ # Main library package
35+
├── STRUCTURE.md # See blockapi/STRUCTURE.md for library architecture details
36+
├── __init__.py # Core API functions and dynamic discovery
37+
├── services.py # Base service classes and HTTP infrastructure
38+
├── test_data.py # Test addresses and API key management
39+
├── test/ # Comprehensive test suite
40+
│ └── STRUCTURE.md # See blockapi/test/STRUCTURE.md for test documentation
41+
├── utils/ # Common utility functions
42+
│ └── STRUCTURE.md # See blockapi/utils/STRUCTURE.md for utilities documentation
43+
└── v2/ # Modern v2 implementation
44+
└── STRUCTURE.md # See blockapi/v2/STRUCTURE.md for v2 architecture
45+
```
46+
47+
## Configuration Files
48+
49+
### `setup.py`
50+
Defines package metadata and dependencies:
51+
- **Version**: 1.3.0 (as of last update)
52+
- **Core Dependencies**: requests, pytz, coinaddrng, web3, pydantic
53+
- **Blockchain-Specific**: solders (Solana), ethereum_input_decoder
54+
- **Utilities**: fake_useragent, beautifulsoup4, lxml
55+
- **Testing**: pytest, pytest-vcr, requests_mock
56+
57+
### `pyproject.toml`
58+
Development tooling configuration:
59+
- **Black**: Line length 88, skip string normalization
60+
- **isort**: Black-compatible profile
61+
- **semantic-release**: Version tracking in setup.py
62+
63+
### `pytest.ini`
64+
Test framework configuration:
65+
- **Markers**: `integration` for tests requiring actual API connections
66+
- **Python Path**: Current directory for imports
67+
68+
### `Makefile`
69+
Development workflow automation:
70+
- `make install`: Install library locally
71+
- `make test`: Run v1 tests
72+
- `make test-v2-api`: Run v2 API tests
73+
- `make dist`: Build and publish to PyPI
74+
75+
## Core Functionality
76+
77+
### Public API (blockapi/__init__.py)
78+
- `get_balance_from_random_api(symbol, address)`: Fetches balance using suitable API
79+
- `get_api_classes_for_coin(symbol)`: Returns all APIs supporting a cryptocurrency
80+
- `get_all_supported_coins()`: Lists all supported cryptocurrency symbols
81+
- `check_address_valid(symbol, address)`: Validates blockchain addresses
82+
- `get_working_apis_for_coin(symbol)`: Tests and returns functional APIs
83+
84+
### Key Components
85+
- **blockapi/**: Core v1 implementation and library entry point - See [blockapi/STRUCTURE.md](blockapi/STRUCTURE.md)
86+
- **blockapi/v2/**: Modern architecture with enhanced features - See [blockapi/v2/STRUCTURE.md](blockapi/v2/STRUCTURE.md)
87+
- **blockapi/utils/**: Shared utilities for address, datetime, and number handling - See [blockapi/utils/STRUCTURE.md](blockapi/utils/STRUCTURE.md)
88+
- **blockapi/test/**: Comprehensive test coverage for both v1 and v2 - See [blockapi/test/STRUCTURE.md](blockapi/test/STRUCTURE.md)
89+
90+
## Supported Blockchains and Features
91+
92+
### Native Blockchain Support (v2)
93+
- **Bitcoin Family**: BTC, LTC, DOGE (via Blockchair, Trezor)
94+
- **Ethereum & L2s**: ETH, Optimism (via Ethplorer, Etherscan)
95+
- **Cosmos Ecosystem**: ATOM, OSMO, DYDX, TIA (via native APIs)
96+
- **Solana**: SOL and SPL tokens (via RPC, Solscan)
97+
- **Polkadot/Kusama**: DOT, KSM (via Subscan)
98+
- **Others**: SUI, Terra, BOS
99+
100+
### Multi-Chain Aggregators
101+
- **DeBank**: 40+ chains with DeFi protocol integration
102+
- **Covalenth**: 15+ EVM chains with unified API
103+
- **SimpleHash**: NFT data across multiple chains
104+
105+
### Specialized Integrations
106+
- **NFT Marketplaces**: OpenSea, Magic Eden, SimpleHash, UniSat
107+
- **DeFi Protocols**: Synthetix, Perpetual Protocol
108+
- **Explorers**: Blockchair, Ethplorer, Subscan, various chain-specific explorers
109+
110+
## Usage Examples
111+
112+
### Basic Balance Query (v1)
113+
```python
114+
import blockapi
115+
116+
# Get Bitcoin balance using random API
117+
balance = blockapi.get_balance_from_random_api('BTC', '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa')
118+
119+
# Validate Ethereum address
120+
is_valid = blockapi.check_address_valid('ETH', '0x...')
121+
```
122+
123+
### Advanced Usage (v2)
124+
```python
125+
from blockapi.v2.api import SolanaApi, DebankApi
126+
from blockapi.v2.models import Blockchain
127+
128+
# Native blockchain API
129+
solana = SolanaApi()
130+
balances = solana.get_balance("11111111111111111111111111111111")
131+
132+
# DeFi portfolio aggregation
133+
debank = DebankApi(api_key="YOUR_KEY", is_all=True)
134+
portfolio = debank.get_portfolio("0x...")
135+
136+
# Custom RPC endpoint
137+
from blockapi.v2.api import EthereumApi
138+
eth = EthereumApi(base_url="https://mainnet.infura.io/v3/YOUR_KEY")
139+
```
140+
141+
## Development Workflow
142+
143+
### Installation
144+
```bash
145+
# Development installation
146+
pip install -e .
147+
148+
# Or using make
149+
make install
150+
```
151+
152+
### Testing
153+
```bash
154+
# Run all tests
155+
pytest
156+
157+
# Run v1 tests only
158+
make test
159+
160+
# Run v2 tests only
161+
make test-v2-api
162+
163+
# Skip integration tests
164+
pytest -m "not integration"
165+
```
166+
167+
### Publishing
168+
```bash
169+
# Build and publish to PyPI
170+
make dist
171+
```
172+
173+
## Important Conventions
174+
175+
1. **Symbol Format**: Always uppercase (BTC, ETH, SOL)
176+
2. **Address Validation**: Performed before API calls
177+
3. **Error Handling**: APIs return None on failure rather than raising
178+
4. **Decimal Precision**: All monetary values use Decimal type
179+
5. **API Keys**: Retrieved from environment variables
180+
6. **Rate Limiting**: Automatic throttling based on API limits
181+
7. **Timezone**: All datetime objects use UTC
182+
183+
## Dependencies and Requirements
184+
185+
### Runtime Dependencies
186+
- Python 3.x
187+
- Core: requests, pytz, coinaddrng
188+
- Blockchain-specific: web3, solders, ethereum_input_decoder
189+
- Data modeling: pydantic, attrs
190+
- Utilities: beautifulsoup4, fake_useragent
191+
192+
### Development Dependencies
193+
- Testing: pytest, pytest-vcr, requests_mock
194+
- Formatting: black, isort
195+
- Build: setuptools, twine
196+
197+
## Integration with Crypkit
198+
199+
As documented in the main CLAUDE.md, blockapi serves as the blockchain data layer for Crypkit:
200+
- Used by microservices for balance and transaction data
201+
- Integrated with currencies-module for price correlation
202+
- Provides portfolio data for frontend display
203+
- Enables cross-chain asset tracking
204+
205+
## Future Extensibility
206+
207+
The architecture supports:
208+
- Adding new blockchain APIs by implementing base interfaces
209+
- Extending to new DeFi protocols through standardized models
210+
- Integrating additional NFT marketplaces
211+
- Enhanced caching and WebSocket support
212+
- Cross-chain interoperability features

0 commit comments

Comments
 (0)