Content
# Pagra AI - Starknet Wallet API
A comprehensive Node.js API for Starknet wallet management with Telegram bot integration and MCP (Model Context Protocol) chat functionality.
## 🚀 Quick Start
### Prerequisites
- Node.js (v16 or higher)
- npm or yarn
- Supabase account and project
- Starknet RPC endpoint access
### Installation
1. **Clone and install dependencies:**
```bash
npm install
```
2. **Environment Setup:**
Create a `.env` file in the root directory with the following variables:
```env
# Server Configuration
PORT=3000
NODE_ENV=development
# Supabase Configuration
SUPABASE_URL=your_supabase_project_url
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
# Starknet Configuration
STARKNET_RPC_URL=your_starknet_rpc_url
STARKNET_NETWORK=sepolia
# Telegram Bot (Optional)
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
# MCP Configuration
ANTHROPIC_API_KEY=your_anthropic_api_key
# Security
JWT_SECRET=your_jwt_secret_here
ENCRYPTION_KEY=your_32_byte_encryption_key
```
3. **Database Setup:**
- Run the database migration scripts from the `migrations/` folder
- See `migrations/README.md` for detailed instructions
### Running the Application
**Development mode (with auto-reload):**
```bash
npm run dev
```
**Production mode:**
```bash
npm start
```
The server will start on `http://localhost:3000`
## 📁 Project Structure
```
pagra-ai/
├── src/ # Source code
│ ├── config/ # Configuration files
│ ├── helpers/ # Helper functions and utilities
│ ├── services/ # Service layer (Telegram, etc.)
│ └── server.js # Main server file
├── tests/ # Test files and utilities
│ ├── mocks/ # Mock files for testing
│ ├── *.test.js # Jest test files
│ ├── test-*.js # Manual test scripts
│ └── README.md # Testing documentation
├── migrations/ # Database migration scripts
│ ├── *.sql # SQL migration files
│ └── README.md # Migration documentation
├── docs/ # Documentation
│ ├── telegram-setup.md # Telegram bot setup guide
│ ├── mcp-chat-example.md # MCP chat examples
│ ├── TEST_SCENARIOS.md # Testing scenarios
│ └── README.md # Documentation index
├── .env # Environment variables (create this)
├── package.json
└── README.md # This file
```
## 🔗 API Endpoints
### Core Wallet Operations
- `POST /api/start` - Create new wallet account
- `POST /api/deploy_account` - Deploy wallet to Starknet
- `POST /api/get_wallet_address` - Get wallet address
- `POST /api/get_balance` - Check wallet balance
- `POST /api/transfer` - Transfer funds
- `POST /api/get_transactions` - Get transaction history
### Chat & AI Integration
- `POST /api/chat` - Process chat messages with MCP
- `POST /api/chat/clear` - Clear conversation history
- `GET /api/chat/history/:phone_number` - Get chat history
### Telegram Integration
- `POST /api/telegram/webhook` - Telegram webhook endpoint
- `POST /api/telegram/set-webhook` - Set webhook URL
### System
- `GET /health` - Health check endpoint
- `GET /api-docs` - Swagger API documentation
## 🛠️ Available Scripts
- `npm run dev` - Start development server with nodemon
- `npm start` - Start production server
- `npm test` - Run Jest tests
- `npm run test:watch` - Run tests in watch mode
- `npm run test:coverage` - Generate test coverage report
## 🧪 Testing
The project includes comprehensive testing:
- **Automated Tests**: Jest-based unit and integration tests
- **Manual Tests**: Interactive testing scripts
- **Telegram Tests**: Bot integration testing
- **MCP Tests**: Chat functionality testing
See `tests/README.md` for detailed testing instructions.
## 🗄️ Database
The project uses Supabase PostgreSQL with:
- **Users table**: Wallet and user information
- **Transactions table**: Transfer history and status
- **Row Level Security**: Secure data access
- **Helper functions**: Database utilities
See `migrations/README.md` for database setup instructions.
## 🤖 Features
### Wallet Management
- ✅ Create Starknet wallets
- ✅ Deploy accounts to network
- ✅ Transfer funds between wallets
- ✅ Check balances and transaction history
- ✅ Secure private key encryption
### Telegram Bot
- ✅ Interactive wallet operations via Telegram
- ✅ Polling mode for development
- ✅ Webhook mode for production
- ✅ Natural language commands
### AI Chat Integration
- ✅ MCP (Model Context Protocol) support
- ✅ Context-aware conversations
- ✅ Tool integration for wallet operations
- ✅ Conversation history management
### Security
- ✅ PIN-based authentication
- ✅ Private key encryption
- ✅ Rate limiting
- ✅ Input validation
- ✅ Row Level Security (RLS)
## 🔧 Dependencies
### Core
- **Express** - Web framework
- **Supabase** - Database and backend services
- **Starknet.js** - Starknet blockchain integration
### Security & Middleware
- **CORS** - Cross-origin resource sharing
- **Helmet** - Security middleware
- **Morgan** - HTTP request logger
- **express-rate-limit** - Rate limiting
### Integrations
- **node-telegram-bot-api** - Telegram bot integration
- **@anthropic-ai/sdk** - Claude AI integration
- **swagger-ui-express** - API documentation
### Development
- **Nodemon** - Development auto-reload
- **Jest** - Testing framework
- **Dotenv** - Environment variable management
## 📚 Documentation
Comprehensive documentation is available in the `docs/` folder:
- **Telegram Setup**: Complete bot integration guide
- **MCP Chat Examples**: AI chat functionality examples
- **Test Scenarios**: Testing strategies and procedures
## 🚨 Important Security Notes
1. **Never commit `.env` files** to version control
2. **Use strong encryption keys** (32 bytes minimum)
3. **Enable RLS policies** in Supabase
4. **Validate all user inputs** before processing
5. **Use HTTPS in production** environments
6. **Regularly rotate API keys** and secrets
## 🆘 Troubleshooting
### Common Issues
- **Supabase connection**: Check environment variables and project status
- **Starknet RPC errors**: Verify RPC URL and network configuration
- **Telegram bot issues**: Ensure bot token is valid and webhook is set
- **Database permissions**: Run `migrations/fix-permissions.sql`
### Getting Help
1. Check the relevant documentation in `docs/`
2. Review test files in `tests/` for examples
3. Verify environment configuration
4. Check server logs for detailed error messages
## 🔄 Development Workflow
1. **Setup**: Follow installation instructions
2. **Database**: Run migrations from `migrations/`
3. **Testing**: Use test scripts in `tests/`
4. **Documentation**: Update relevant docs when adding features
5. **Deployment**: Use production environment variables
## 📈 Next Steps
1. Set up your Supabase database using migration scripts
2. Configure Telegram bot (optional) using `docs/telegram-setup.md`
3. Test API endpoints using provided test scripts
4. Implement additional features as needed
5. Deploy to production environment
