Skip to content

Commit 753c4d0

Browse files
CopilotSMSDAO
Copilot
and
SMSDAO
committed
Add GitHub Copilot instructions for repository
Co-authored-by: SMSDAO <[email protected]>
1 parent d2805c0 commit 753c4d0

1 file changed

Lines changed: 295 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,295 @@
1+
# GitHub Copilot Custom Instructions
2+
3+
This repository contains the GXQ STUDIO - Advanced Solana DeFi Platform with flash loan arbitrage, sniper bot, token launchpad, and a Next.js web application.
4+
5+
## Project Structure
6+
7+
### Backend (Root)
8+
- **Language**: TypeScript (ES2022 modules)
9+
- **Main Entry**: `src/index.ts`
10+
- **Output**: `dist/` directory
11+
- **Key Directories**:
12+
- `src/config/` - Configuration and token definitions
13+
- `src/providers/` - Flash loan provider implementations (Marginfi, Solend, Kamino, Mango, Port Finance)
14+
- `src/dex/` - DEX integrations (Raydium, Orca, Serum, Jupiter, etc.)
15+
- `src/integrations/` - QuickNode and Jupiter integrations
16+
- `src/services/` - Core services (airdrop, presets, auto-execution)
17+
- `src/strategies/` - Arbitrage strategies
18+
- `src/types.ts` - TypeScript type definitions
19+
20+
### Frontend (webapp/)
21+
- **Framework**: Next.js 16 with App Router
22+
- **Language**: TypeScript, React 19
23+
- **Styling**: Tailwind CSS 4
24+
- **Key Features**: Jupiter Swap, Sniper Bot, Token Launchpad, Airdrop Checker, Staking, Flash Loan Arbitrage
25+
26+
## Coding Standards
27+
28+
### TypeScript
29+
- Use strict TypeScript with `strict: true` in tsconfig.json
30+
- Target ES2022 with ES2022 modules
31+
- Always use explicit types; avoid `any` (warning level in ESLint)
32+
- Use ESM syntax (`import`/`export`, not `require`)
33+
- Prefix unused parameters with underscore (`_param`)
34+
35+
### Code Style
36+
- Follow `.eslintrc.json` rules for backend
37+
- Follow `eslint.config.mjs` rules for webapp
38+
- Use 2-space indentation
39+
- Use semicolons consistently
40+
- Use async/await for asynchronous operations
41+
- Use descriptive variable names (camelCase for variables, PascalCase for types/classes)
42+
43+
### Imports
44+
- Group imports: external libraries, then internal modules
45+
- Use absolute paths from `src/` for backend
46+
- Use relative paths or aliases for webapp
47+
48+
## Security Requirements
49+
50+
### Critical Security Rules
51+
- **Never commit private keys, mnemonics, or secrets** to source code
52+
- All sensitive data must be loaded from environment variables
53+
- Use `.env.example` as a template; never commit actual `.env` files
54+
- Validate all user input before processing
55+
- Always use type-safe Solana transaction builders
56+
57+
### Solana Security
58+
- Never expose private keys in logs or error messages
59+
- Validate all Solana addresses before transactions
60+
- Use proper slippage protection for DEX trades
61+
- Implement MEV protection via Jito bundles when executing arbitrage
62+
- Always check transaction confirmations before assuming success
63+
- Use proper priority fees to ensure transaction inclusion
64+
65+
### API Keys & Credentials
66+
- Store all RPC URLs, API keys, and credentials in environment variables
67+
- Use QuickNode RPC for production (not free public endpoints)
68+
- Implement rate limiting for API calls
69+
- Handle API errors gracefully with retries and exponential backoff
70+
71+
## Testing Requirements
72+
73+
### Test Coverage
74+
- Write unit tests for new utility functions
75+
- Write integration tests for Solana transaction logic
76+
- Use Jest for testing framework
77+
- Test files should be co-located or in `__tests__` directories
78+
- Mock external API calls in tests
79+
80+
### Testing Patterns
81+
- Test error handling paths
82+
- Test edge cases (e.g., insufficient balance, failed transactions)
83+
- Test with devnet/testnet addresses, never mainnet in tests
84+
- Validate transaction structure before signing
85+
86+
## Dependencies Management
87+
88+
### Adding Dependencies
89+
- Backend: Use `npm install` in root directory
90+
- Frontend: Use `npm install` in `webapp/` directory
91+
- Prefer well-maintained packages with active communities
92+
- Check security advisories before adding new dependencies
93+
- Document why new dependencies are needed in PRs
94+
95+
### Key Dependencies
96+
- `@solana/web3.js` - Solana blockchain interaction
97+
- `@jup-ag/api` - Jupiter aggregator for token swaps
98+
- `@solana/spl-token` - SPL token operations
99+
- `next` - Next.js framework for webapp
100+
- `react` - React library
101+
- `axios` - HTTP client for API calls
102+
- `dotenv` - Environment variable management
103+
104+
## Build & Development
105+
106+
### Backend Build Process
107+
```bash
108+
npm install # Install dependencies
109+
npm run build # TypeScript compilation to dist/
110+
npm run lint # Run ESLint
111+
npm test # Run Jest tests
112+
npm start # Run compiled code from dist/
113+
npm run dev # Run with ts-node-esm for development
114+
```
115+
116+
### Webapp Build Process
117+
```bash
118+
cd webapp
119+
npm install # Install dependencies
120+
npm run dev # Start development server
121+
npm run build # Build for production
122+
npm run lint # Run ESLint
123+
npm start # Start production server
124+
```
125+
126+
### Common Commands
127+
- `npm start airdrops` - Check available airdrops
128+
- `npm start claim` - Auto-claim airdrops
129+
- `npm start scan` - Scan for arbitrage opportunities
130+
- `npm start start` - Start auto-execution mode
131+
- `npm start manual` - Manual execution mode
132+
133+
## Architecture Guidelines
134+
135+
### Backend Architecture
136+
- Use service-oriented architecture
137+
- Keep business logic in `services/`
138+
- Keep external integrations in `integrations/`
139+
- Use strategy pattern for arbitrage strategies
140+
- Implement proper error handling with try-catch blocks
141+
- Log important events and errors
142+
143+
### Frontend Architecture
144+
- Use React Server Components where possible
145+
- Keep client components minimal (`'use client'` directive)
146+
- Use Tailwind for styling (no custom CSS files)
147+
- Implement proper loading states
148+
- Use React hooks for state management
149+
- Implement proper error boundaries
150+
151+
## Flash Loan & DeFi Patterns
152+
153+
### Flash Loan Implementation
154+
- Check liquidity availability before attempting flash loans
155+
- Calculate profitability including fees (0.09%-0.20% depending on provider)
156+
- Implement atomic transaction bundling
157+
- Always repay flash loan in same transaction
158+
- Include safety checks for minimum profit thresholds
159+
160+
### DEX Integration
161+
- Use Jupiter aggregator for best routing
162+
- Implement proper slippage calculation
163+
- Handle transaction failures gracefully
164+
- Monitor for price impact
165+
- Use versioned APIs (Jupiter v6, etc.)
166+
167+
### Arbitrage Strategy
168+
- Minimum profit threshold: 0.3%-1.0% depending on risk
169+
- Dynamic slippage based on volatility
170+
- Support for triangular and flash loan arbitrage
171+
- MEV protection via Jito bundles
172+
- Dev fee system (10% of profits)
173+
174+
## Documentation
175+
176+
### Code Documentation
177+
- Add JSDoc comments for public functions
178+
- Document complex algorithms with inline comments
179+
- Keep README files up to date
180+
- Document environment variables in `.env.example`
181+
- Update documentation when changing functionality
182+
183+
### API Documentation
184+
- Document all public API endpoints
185+
- Include request/response examples
186+
- Document error codes and messages
187+
- Keep OpenAPI/Swagger specs updated if applicable
188+
189+
## Deployment
190+
191+
### Vercel Deployment (Webapp)
192+
- Set Root Directory to `webapp` in Vercel settings
193+
- Add `NEXT_PUBLIC_RPC_URL` environment variable
194+
- Use preview deployments for testing
195+
- See `VERCEL_DEPLOY.md` for detailed instructions
196+
197+
### Environment Configuration
198+
- Use `.env.example` as template
199+
- Required variables: `SOLANA_RPC_URL`, `WALLET_PRIVATE_KEY`
200+
- Optional: QuickNode configuration for advanced features
201+
- Configure profit thresholds and slippage settings
202+
203+
## Solana-Specific Guidelines
204+
205+
### Transaction Building
206+
- Use `@solana/web3.js` Transaction builder
207+
- Add compute budget instructions when needed
208+
- Set appropriate priority fees
209+
- Always simulate transactions before sending
210+
- Handle transaction confirmation properly
211+
212+
### Account Management
213+
- Use proper account derivation (PDA)
214+
- Check account ownership before operations
215+
- Validate account data before reading
216+
- Handle account creation fees (rent-exemption)
217+
218+
### Token Operations
219+
- Use `@solana/spl-token` for token operations
220+
- Check token mint addresses
221+
- Validate token decimals
222+
- Handle associated token accounts properly
223+
- Check token balances before operations
224+
225+
## Error Handling
226+
227+
### Error Patterns
228+
- Use try-catch for async operations
229+
- Log errors with context (transaction signatures, amounts, etc.)
230+
- Return meaningful error messages to users
231+
- Implement retry logic with exponential backoff
232+
- Handle network timeouts gracefully
233+
234+
### Common Errors to Handle
235+
- Insufficient balance
236+
- Transaction timeout
237+
- RPC node errors
238+
- Failed transaction confirmation
239+
- Slippage exceeded
240+
- Price impact too high
241+
242+
## Performance Considerations
243+
244+
### Backend Performance
245+
- Use connection pooling for RPC
246+
- Cache frequently accessed data (token prices, account info)
247+
- Implement rate limiting to avoid RPC quota exhaustion
248+
- Use batch requests where possible
249+
- Monitor transaction confirmation times
250+
251+
### Frontend Performance
252+
- Optimize images and assets
253+
- Use Next.js Image component
254+
- Implement code splitting
255+
- Lazy load heavy components
256+
- Minimize client-side bundle size
257+
- Use React.memo for expensive renders
258+
259+
## Git & Version Control
260+
261+
### Commit Messages
262+
- Use conventional commits format
263+
- Be descriptive but concise
264+
- Reference issue numbers when applicable
265+
266+
### Branch Strategy
267+
- Create feature branches from main
268+
- Use descriptive branch names
269+
- Keep branches focused and small
270+
- Squash commits before merging if needed
271+
272+
## Additional Guidelines
273+
274+
### Risk & Disclaimers
275+
- This involves financial operations with real assets
276+
- Always test thoroughly on devnet/testnet first
277+
- Include appropriate risk disclaimers
278+
- Never guarantee profitability in documentation
279+
- Warn users about smart contract risks, volatility, and potential losses
280+
281+
### Monitoring & Logging
282+
- Log all transaction attempts and results
283+
- Monitor RPC health and switch endpoints if needed
284+
- Track profitability metrics
285+
- Alert on failures or anomalies
286+
287+
### Community & Support
288+
- Keep issues updated with progress
289+
- Respond to community feedback
290+
- Document known issues and limitations
291+
- Provide troubleshooting guides
292+
293+
---
294+
295+
**Remember**: This is a financial application dealing with real cryptocurrency. Prioritize security, accuracy, and user protection in all code changes.

0 commit comments

Comments
 (0)