CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7The SettleMint SDK is a comprehensive blockchain development toolkit and platform integration suite. It provides developers with tools to build, deploy, and manage blockchain applications using the SettleMint platform's infrastructure and services.
8 
9### Technology Stack
10 
11**Core Technologies**
12- Runtime: Bun (fast JavaScript runtime)
13- Package Manager: Bun workspaces with Turbo
14- Language: TypeScript (strict mode)
15- Code Quality: Biome for linting and formatting
16- Testing: Vitest for unit/integration tests
17- Documentation: TypeDoc
18- GraphQL: Apollo Client, GraphQL Code Generator
19- Blockchain: Viem, Ethers, Foundry, Hardhat support
20 
21**Monorepo Structure**
22- sdk/ - All SDK packages (13 packages total)
23- test/ - End-to-end tests
24- docs/ - Documentation
25- scripts/ - Build and utility scripts
26- fixtures/ - Test fixtures
27 
28**SDK Packages**
29- @settlemint/sdk-cli - Command-line interface
30- @settlemint/sdk-js - Core JavaScript SDK
31- @settlemint/sdk-portal - Smart contract portal API
32- @settlemint/sdk-viem - Ethereum interface (Viem)
33- @settlemint/sdk-blockscout - Blockchain explorer
34- @settlemint/sdk-eas - Ethereum Attestation Service
35- @settlemint/sdk-hasura - GraphQL/PostgreSQL
36- @settlemint/sdk-ipfs - Decentralized storage
37- @settlemint/sdk-minio - S3-compatible storage
38- @settlemint/sdk-thegraph - Blockchain indexing
39- @settlemint/sdk-next - Next.js components
40- @settlemint/sdk-mcp - Model Context Protocol
41- @settlemint/sdk-utils - Shared utilities
42 
43**Key Features**
44- Multi-chain blockchain support
45- Smart contract deployment and verification
46- Platform service integration
47- Developer tooling and scaffolding
48- GraphQL API generation
49- TypeScript type generation
50- Comprehensive CLI tools
51- Example applications
52 
53## Essential Commands
54 
55### Development Workflow
56```bash
57# Setup
58bun install                  # Install dependencies (root)
59bun install --frozen-lockfile # CI-safe install
60 
61# Development
62bun run dev                  # Start development (turbo)
63bun run dev:cli             # Develop CLI package
64bun run dev:portal          # Develop portal package
65 
66# Building
67bun run build               # Build all packages
68bun run build:cli          # Build CLI package
69bun run build:sdk          # Build SDK packages
70 
71# Testing
72bun test                    # Run all tests
73bun test:unit              # Run unit tests
74bun test:e2e               # Run e2e tests
75bun test:coverage          # Generate coverage report
76 
77# Code Quality
78bun run lint               # Run Biome linter
79bun run lint:fix          # Fix linting issues
80bun run format            # Format with Biome
81bun run typecheck         # Run TypeScript checks
82 
83# Documentation
84bun run docs              # Generate TypeDoc docs
85bun run docs:build       # Build documentation
86 
87# Publishing
88bun run changeset         # Create changeset
89bun run version          # Version packages
90bun run release          # Release packages
91```
92 
93### Package Development
94```bash
95# Work on specific packages
96cd sdk/cli && bun run dev    # CLI development
97cd sdk/js && bun test        # Test JS SDK
98cd sdk/portal && bun build   # Build portal
99 
100# Run package scripts
101turbo run build --filter=@settlemint/sdk-cli
102turbo run test --filter=@settlemint/sdk-*
103```
104 
105## Architecture & Code Organization
106 
107### Repository Structure
108```
109/
110├── sdk/                      # SDK packages (monorepo)
111│   ├── cli/                  # CLI tool (@settlemint/sdk-cli)
112│   ├── js/                   # Core SDK (@settlemint/sdk-js)
113│   ├── portal/               # Portal API (@settlemint/sdk-portal)
114│   ├── viem/                 # Viem integration (@settlemint/sdk-viem)
115│   ├── blockscout/           # Explorer integration
116│   ├── eas/                  # Attestation service
117│   ├── hasura/               # GraphQL/PostgreSQL
118│   ├── ipfs/                 # IPFS integration
119│   ├── minio/                # S3 storage
120│   ├── thegraph/             # Subgraph integration
121│   ├── next/                 # Next.js components
122│   ├── mcp/                  # MCP interface
123│   └── utils/                # Shared utilities
124├── test/                     # E2E tests
125├── docs/                     # Documentation
126├── scripts/                  # Build scripts
127├── fixtures/                 # Test fixtures
128├── turbo.json               # Turbo config
129├── biome.json               # Biome config
130└── package.json             # Root package
131```
132 
133### Key Architecture Patterns
134 
1351. **Monorepo Structure**
136   - Bun workspaces for package management
137   - Turbo for build orchestration
138   - Shared dependencies and tooling
139   - Independent package versioning
140 
1412. **TypeScript-First Development**
142   - Strict TypeScript configuration
143   - Type generation for GraphQL
144   - Shared type definitions in utils
145   - Runtime validation with Zod
146 
1473. **SDK Design Principles**
148   - Each package is independently usable
149   - Minimal dependencies between packages
150   - Consistent API design across packages
151   - Comprehensive TypeScript types
152 
1534. **Platform Integration**
154   - GraphQL for API communication
155   - RESTful endpoints where appropriate
156   - WebSocket support for real-time data
157   - Authentication and authorization built-in
158 
159## Development Guidelines
160 
161### TypeScript Conventions
162- **NO default exports** (except when framework requires)
163- Use `import type` for type imports
164- Prefer interfaces over type aliases for objects
165- **Never use `any`** - use `unknown` or proper types
166- Use discriminated unions for error handling
167- Naming conventions:
168  - Files: kebab-case
169  - Variables/functions: camelCase
170  - Types/interfaces/classes: PascalCase
171  - Constants: UPPER_SNAKE_CASE
172 
173### Code Style Rules
174- Prefer nullish coalescing (`??`) over logical OR (`||`)
175- Use early returns to reduce nesting
176- Extract complex logic into well-named functions
177- Keep functions small and focused
178- Use structured logging with proper context
179 
180### API Design Principles
181- RESTful conventions for HTTP endpoints
182- GraphQL for complex queries and subscriptions
183- Consistent error responses
184- Proper HTTP status codes
185- Comprehensive OpenAPI documentation
186 
187### Blockchain Best Practices
188- Always validate addresses before use
189- Handle chain-specific differences properly
190- Implement proper gas estimation
191- Use type-safe contract interactions
192- Never store private keys in code or logs
193 
194### Git Workflow
195- **Never push to main branch**
196- Branch naming: `feat/`, `fix/`, `chore/`, etc.
197- Commit format: `type(scope): description`
198- Create PRs for all changes
199- Ensure CI passes before merge
200 
201## Claude Code Best Practices
202 
203- Always read entire files before making changes
204- Run tests after modifications
205- Check existing patterns before implementing new features
206- Use the project's established error handling patterns
207- Validate all blockchain interactions
208- Keep security in mind - never expose sensitive data
209- Use queue jobs for long-running operations
210- Implement proper retry logic for external calls
211 
212## Package-Specific Guidelines
213 
214### SDK CLI (@settlemint/sdk-cli)
215- Main entry point for developers
216- Provides project scaffolding
217- Handles authentication flows
218- Manages deployments and configurations
219 
220### SDK JS (@settlemint/sdk-js)
221- Core platform integration
222- API client for SettleMint services
223- Authentication and authorization
224- Resource management (nodes, networks, etc.)
225 
226### SDK Portal (@settlemint/sdk-portal)
227- Smart contract portal integration
228- Contract deployment and verification
229- Transaction management
230- Event monitoring
231 
232### SDK Viem (@settlemint/sdk-viem)
233- Viem-based blockchain interactions
234- Multi-chain support
235- Type-safe contract calls
236- Transaction helpers
237 
238## Testing Guidelines
239 
240- Write unit tests using Vitest
241- E2E tests for CLI commands
242- Mock external API calls
243- Test error scenarios
244- Use test fixtures for consistency
245- Follow AAA pattern (Arrange, Act, Assert)
246 
247## Environment Configuration
248 
249Key environment variables:
250- `SETTLEMINT_API_URL` - Platform API endpoint
251- `SETTLEMINT_AUTH_TOKEN` - Authentication token
252- `NODE_ENV` - Environment (development/production)
253 
254Package-specific configs:
255- Each SDK package may have its own configuration
256- Check individual package README files
257- Use `.env` files for local development
258 
259## Troubleshooting
260 
261### Common Issues
2621. **Build errors**: Run `bun install` and `bun run build`
2632. **Type errors**: Check with `bun run typecheck`
2643. **Linting issues**: Fix with `bun run lint:fix`
2654. **Test failures**: Check test output and mocks
266 
267### Development Tips
268- Use Turbo's cache for faster builds
269- Run specific package tests with filters
270- Check individual package README files
271- Use `--verbose` flag for detailed output
272 
273## Before Creating a PR
274 
2751. **Run tests**: `bun test`
2762. **Type check**: `bun run typecheck`
2773. **Lint code**: `bun run lint`
2784. **Format code**: `bun run format`
2795. **Update documentation** if needed
2806. **Test locally** with different scenarios
281 
282## Project-Specific Notes
283 
284- This is a developer SDK, not an application
285- Supports the SettleMint blockchain platform
286- Each package can be used independently
287- Follow semantic versioning for releases
288- Documentation is essential for all public APIs
289 
290## Command Reference
291 
292Use these Claude Code commands when appropriate:
293- `/pr` - Create pull requests
294- `/qa` - Run quality checks
295- `/explore` - Understand architecture
296- `/stuck` - Debug systematically
297- `/deps` - Update dependencies safely
298- `/performance` - Analyze performance
299 
300## MCP Server Usage
301 
302### Linear (Project Management)
303When working with Linear tickets, use the MCP Linear tools:
304 
305```
306# Search for issues
307mcp__linear__list_issues(query="ENG-3236", limit=10)
308 
309# Get issue details
310mcp__linear__get_issue(id="ENG-3236")
311 
312# Update issue with comment and/or status
313mcp__linear__update_issue(
314  id="ENG-3236",
315  stateId="<state-id>",  # Optional: update status
316  description="Updated description"  # Optional: update description
317)
318 
319# Create comment on issue
320mcp__linear__create_comment(
321  issueId="<issue-id>",
322  body="PR created: https://github.com/..."
323)
324 
325# List issue statuses to find stateId
326mcp__linear__list_issue_statuses(teamId="<team-id>")
327```
328 
329When you create a PR for a Linear ticket:
3301. Add a comment with the PR link using `mcp__linear__create_comment`
3312. Update the issue status if needed using `mcp__linear__update_issue`
3323. Include the Linear issue ID in the PR description for automatic linking
333 
334### Sentry (Error Tracking)
335Use Sentry MCP tools for error investigation:
336 
337```
338# Find organizations you have access to
339mcp__sentry__find_organizations()
340 
341# Find issues in an organization
342mcp__sentry__find_issues(
343  organizationSlug="settlemint",
344  query="is:unresolved",
345  sortBy="last_seen"
346)
347 
348# Get detailed error information
349mcp__sentry__get_issue_details(
350  organizationSlug="settlemint",
351  issueId="PROJECT-123"
352)
353 
354# Update issue status
355mcp__sentry__update_issue(
356  organizationSlug="settlemint",
357  issueId="PROJECT-123",
358  status="resolved"
359)
360```
361 
362### Context7 (Documentation)
363Use for checking latest documentation:
364 
365```
366# Search for library documentation
367mcp__context7__resolve-library-id(libraryName="viem")
368 
369# Get library docs
370mcp__context7__get-library-docs(
371  context7CompatibleLibraryID="/wagmi-dev/viem",
372  topic="contract-interactions"
373)
374```
375 
376### DeepWiki (GitHub Documentation)
377Use for repository documentation:
378 
379```
380# Get repository documentation structure
381mcp__deepwiki__read_wiki_structure(repoName="wagmi-dev/viem")
382 
383# Read repository documentation
384mcp__deepwiki__read_wiki_contents(repoName="wagmi-dev/viem")
385 
386# Ask questions about a repository
387mcp__deepwiki__ask_question(
388  repoName="wagmi-dev/viem",
389  question="How do I deploy a contract?"
390)
391```