.cursor/rules/core.mdc

---
description: Core blockchain interaction components and Solana protocol abstractions. Apply when working with blockchain operations, transactions, or protocol-specific logic.
globs: src/core/*.py
alwaysApply: true
---

# Core Blockchain Components Guide

## Overview

The core module provides essential abstractions and utilities for interacting with the Solana blockchain, managing wallets, handling transactions, and working with protocol-specific logic such as bonding curves and token operations.

## Key Components

### Solana Client

@src/core/client.py implements the `SolanaClient` class which:
- Handles RPC communication with Solana nodes
- Manages transaction submission and confirmation
- Provides methods for account data retrieval and subscription
- Implements retry logic and error handling for blockchain operations

```python
# Example usage
client = SolanaClient(rpc_endpoint, wss_endpoint)
await client.get_token_account_data(token_account)
```

### Wallet Management

@src/core/wallet.py provides wallet functionality:
- Secure private key handling
- Transaction signing
- Account derivation and management
- Integration with hardware wallets (where applicable)

### Public Key Management

@src/core/pubkeys.py contains:
- System address constants
- Program ID references
- Address derivation utilities
- Token account resolution functions

### Bonding Curve Mathematics

@src/core/curve.py offers:
- Mathematical models for bonding curve calculations
- Price impact estimation
- Liquidity modeling
- Swap pricing utilities

### Priority Fee Management

@src/core/priority_fee/manager.py implements:
- Dynamic priority fee calculation
- Fee cap enforcement
- Network congestion detection
- Transaction prioritization strategies

## Common Operations

| Operation | Key Functions |
|-----------|--------------|
| Send Transaction | `client.send_transaction(tx, opts)` |
| Get Account Data | `client.get_account_info(pubkey)` |
| Sign Message | `wallet.sign_message(message)` |
| Calculate Price | `curve.calculate_price_impact(amount)` |

## Related Files

- @src/core/client.py: Solana RPC client implementation
- @src/core/wallet.py: Wallet and signing functionality
- @src/core/pubkeys.py: Address management and derivation
- @src/core/curve.py: Bonding curve and pricing mathematics
- @src/core/priority_fee/manager.py: Transaction fee optimization
docs: add cursor rules 2025-07-14 20:07:50 +00:00			`---`
wip(cursor): craft cursor rules 2025-07-15 14:33:17 +00:00			`description: Core blockchain interaction components and Solana protocol abstractions. Apply when working with blockchain operations, transactions, or protocol-specific logic.`
			`globs: src/core/*.py`
			`alwaysApply: true`
			`---`

			`# Core Blockchain Components Guide`

			`## Overview`

			`The core module provides essential abstractions and utilities for interacting with the Solana blockchain, managing wallets, handling transactions, and working with protocol-specific logic such as bonding curves and token operations.`

			`## Key Components`

			`### Solana Client`

			@src/core/client.py implements the `SolanaClient` class which:
			`- Handles RPC communication with Solana nodes`
			`- Manages transaction submission and confirmation`
			`- Provides methods for account data retrieval and subscription`
			`- Implements retry logic and error handling for blockchain operations`

			```python
			`# Example usage`
			`client = SolanaClient(rpc_endpoint, wss_endpoint)`
			`await client.get_token_account_data(token_account)`
			```

			`### Wallet Management`

			`@src/core/wallet.py provides wallet functionality:`
			`- Secure private key handling`
			`- Transaction signing`
			`- Account derivation and management`
			`- Integration with hardware wallets (where applicable)`

			`### Public Key Management`

			`@src/core/pubkeys.py contains:`
			`- System address constants`
			`- Program ID references`
			`- Address derivation utilities`
			`- Token account resolution functions`

			`### Bonding Curve Mathematics`

			`@src/core/curve.py offers:`
			`- Mathematical models for bonding curve calculations`
			`- Price impact estimation`
			`- Liquidity modeling`
			`- Swap pricing utilities`

			`### Priority Fee Management`

			`@src/core/priority_fee/manager.py implements:`
			`- Dynamic priority fee calculation`
			`- Fee cap enforcement`
			`- Network congestion detection`
			`- Transaction prioritization strategies`

			`## Common Operations`

			`\| Operation \| Key Functions \|`
			`\|-----------\|--------------\|`
			\| Send Transaction \| `client.send_transaction(tx, opts)` \|
			\| Get Account Data \| `client.get_account_info(pubkey)` \|
			\| Sign Message \| `wallet.sign_message(message)` \|
			\| Calculate Price \| `curve.calculate_price_impact(amount)` \|

			`## Related Files`

			`- @src/core/client.py: Solana RPC client implementation`
			`- @src/core/wallet.py: Wallet and signing functionality`
			`- @src/core/pubkeys.py: Address management and derivation`
			`- @src/core/curve.py: Bonding curve and pricing mathematics`
			`- @src/core/priority_fee/manager.py: Transaction fee optimization`