|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Development Commands |
| 6 | + |
| 7 | +### Environment Setup |
| 8 | +- Use Poetry for dependency management: `poetry install -n` |
| 9 | +- Activate virtual environment: `poetry shell` or `source $(poetry env info --path)/bin/activate` |
| 10 | +- Install additional types for mypy: `make install-types` |
| 11 | + |
| 12 | +### Linting and Formatting |
| 13 | +- Run all linters and formatters: `make lint` or `make pre-commit` |
| 14 | +- Run specific linter: `make pre-commit hook=black` (or flake8, isort, etc.) |
| 15 | +- The project uses pre-commit hooks with: black, isort, flake8, mypy, pylint, bandit, safety |
| 16 | + |
| 17 | +### Testing |
| 18 | +- Run tests: `poetry run pytest` |
| 19 | +- Run tests with coverage: `poetry run pytest --cov` |
| 20 | + |
| 21 | +### Dependency Management |
| 22 | +- Update lockfile: `make lockfile-update` |
| 23 | +- Fully regenerate lockfile: `make lockfile-update-full` |
| 24 | +- Check for security issues: `make check-safety` |
| 25 | + |
| 26 | +### Code Quality Tools Configuration |
| 27 | +- Black line length: 120 characters |
| 28 | +- isort profile: black, line length 120 |
| 29 | +- mypy: strict settings enabled with comprehensive type checking |
| 30 | +- pylint: excludes examples directory, allows up to 2000 lines per module |
| 31 | +- bandit: excludes tests directory |
| 32 | + |
| 33 | +## Architecture Overview |
| 34 | + |
| 35 | +### Three-Component SDK Structure |
| 36 | + |
| 37 | +The SDK is organized into three main components: |
| 38 | + |
| 39 | +#### 1. REST API Client (`sdk/reya_rest_api/`) |
| 40 | +- **Main Class**: `ReyaTradingClient` - Resource-based client for synchronous and asynchronous trading operations |
| 41 | +- **Resources**: wallet, orders, markets, assets, prices |
| 42 | +- **Authentication**: Uses signature generation for secure API requests |
| 43 | +- **Configuration**: Environment-based configuration through `TradingConfig` |
| 44 | + |
| 45 | +#### 2. WebSocket Client (`sdk/reya_websocket/`) |
| 46 | +- **Main Class**: `ReyaSocket` - Resource-oriented WebSocket client for real-time data |
| 47 | +- **Resources**: market (all markets, specific market data/orders), wallet (positions, orders, balances), prices (asset pair prices) |
| 48 | +- **Connection**: Supports both blocking and non-blocking connections with SSL configuration |
| 49 | +- **Configuration**: Environment-based through `WebSocketConfig` |
| 50 | + |
| 51 | +#### 3. RPC Actions (`sdk/reya_rpc/`) |
| 52 | +- **Purpose**: On-chain interactions via Web3 |
| 53 | +- **Actions**: bridge_in, bridge_out, create_account, deposit, withdraw, stake, unstake, trade, transfer, update_oracle_prices |
| 54 | +- **Integration**: Uses Web3, eth-account for blockchain interactions |
| 55 | +- **ABIs**: Contains JSON ABIs for various smart contracts |
| 56 | + |
| 57 | +### Configuration Pattern |
| 58 | +All SDK components use environment-based configuration: |
| 59 | +- REST API: Uses `TradingConfig.from_env()` loading from environment variables |
| 60 | +- WebSocket: Uses `WebSocketConfig.from_env()` with comprehensive connection settings |
| 61 | +- RPC: Uses get_config() for blockchain connection parameters |
| 62 | + |
| 63 | +### Examples Structure |
| 64 | +- `examples/rest_api/`: Demonstrates REST API usage (wallet operations, order management, market data) |
| 65 | +- `examples/websocket/`: Shows real-time data monitoring patterns |
| 66 | +- `examples/rpc/`: Illustrates blockchain interactions and fund flows |
| 67 | + |
| 68 | +### Key Environment Variables |
| 69 | +``` |
| 70 | +ACCOUNT_ID=your_account_id |
| 71 | +PRIVATE_KEY=your_private_key |
| 72 | +CHAIN_ID=1729 # 89346162 for testnet |
| 73 | +REYA_WS_URL=wss://ws.reya.xyz/ # wss://websocket-testnet.reya.xyz/ for testnet |
| 74 | +``` |
| 75 | + |
| 76 | +## Important Development Notes |
| 77 | + |
| 78 | +### Testing Patterns |
| 79 | +- Uses pytest with VCR.py for HTTP request recording/playback |
| 80 | +- Test configuration excludes examples directory from pylint checks |
| 81 | +- Coverage reporting available via pytest-cov |
| 82 | + |
| 83 | +### Authentication & Security |
| 84 | +- Private key-based authentication for API requests |
| 85 | +- Signature generation handled by `SignatureGenerator` class |
| 86 | +- Bandit security scanning excludes test files |
| 87 | +- Safety checks for dependency vulnerabilities |
| 88 | + |
| 89 | +### Code Style Enforcement |
| 90 | +- All components follow black formatting (120 char line length) |
| 91 | +- Type hints required (mypy strict mode enabled) |
| 92 | +- Import sorting via isort with black profile |
| 93 | +- Comprehensive linting via pylint with project-specific disable rules |
0 commit comments