Skip to content

Latest commit

 

History

History
391 lines (319 loc) · 11.6 KB

CLAUDE.md

File metadata and controls

391 lines (319 loc) · 11.6 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

The 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.

Technology Stack

Core Technologies

  • Runtime: Bun (fast JavaScript runtime)
  • Package Manager: Bun workspaces with Turbo
  • Language: TypeScript (strict mode)
  • Code Quality: Biome for linting and formatting
  • Testing: Vitest for unit/integration tests
  • Documentation: TypeDoc
  • GraphQL: Apollo Client, GraphQL Code Generator
  • Blockchain: Viem, Ethers, Foundry, Hardhat support

Monorepo Structure

  • sdk/ - All SDK packages (13 packages total)
  • test/ - End-to-end tests
  • docs/ - Documentation
  • scripts/ - Build and utility scripts
  • fixtures/ - Test fixtures

SDK Packages

  • @settlemint/sdk-cli - Command-line interface
  • @settlemint/sdk-js - Core JavaScript SDK
  • @settlemint/sdk-portal - Smart contract portal API
  • @settlemint/sdk-viem - Ethereum interface (Viem)
  • @settlemint/sdk-blockscout - Blockchain explorer
  • @settlemint/sdk-eas - Ethereum Attestation Service
  • @settlemint/sdk-hasura - GraphQL/PostgreSQL
  • @settlemint/sdk-ipfs - Decentralized storage
  • @settlemint/sdk-minio - S3-compatible storage
  • @settlemint/sdk-thegraph - Blockchain indexing
  • @settlemint/sdk-next - Next.js components
  • @settlemint/sdk-mcp - Model Context Protocol
  • @settlemint/sdk-utils - Shared utilities

Key Features

  • Multi-chain blockchain support
  • Smart contract deployment and verification
  • Platform service integration
  • Developer tooling and scaffolding
  • GraphQL API generation
  • TypeScript type generation
  • Comprehensive CLI tools
  • Example applications

Essential Commands

Development Workflow

# Setup
bun install                  # Install dependencies (root)
bun install --frozen-lockfile # CI-safe install

# Development
bun run dev                  # Start development (turbo)
bun run dev:cli             # Develop CLI package
bun run dev:portal          # Develop portal package

# Building
bun run build               # Build all packages
bun run build:cli          # Build CLI package
bun run build:sdk          # Build SDK packages

# Testing
bun test                    # Run all tests
bun test:unit              # Run unit tests
bun test:e2e               # Run e2e tests
bun test:coverage          # Generate coverage report

# Code Quality
bun run lint               # Run Biome linter
bun run lint:fix          # Fix linting issues
bun run format            # Format with Biome
bun run typecheck         # Run TypeScript checks

# Documentation
bun run docs              # Generate TypeDoc docs
bun run docs:build       # Build documentation

# Publishing
bun run changeset         # Create changeset
bun run version          # Version packages
bun run release          # Release packages

Package Development

# Work on specific packages
cd sdk/cli && bun run dev    # CLI development
cd sdk/js && bun test        # Test JS SDK
cd sdk/portal && bun build   # Build portal

# Run package scripts
turbo run build --filter=@settlemint/sdk-cli
turbo run test --filter=@settlemint/sdk-*

Architecture & Code Organization

Repository Structure

/
├── sdk/                      # SDK packages (monorepo)
│   ├── cli/                  # CLI tool (@settlemint/sdk-cli)
│   ├── js/                   # Core SDK (@settlemint/sdk-js)
│   ├── portal/               # Portal API (@settlemint/sdk-portal)
│   ├── viem/                 # Viem integration (@settlemint/sdk-viem)
│   ├── blockscout/           # Explorer integration
│   ├── eas/                  # Attestation service
│   ├── hasura/               # GraphQL/PostgreSQL
│   ├── ipfs/                 # IPFS integration
│   ├── minio/                # S3 storage
│   ├── thegraph/             # Subgraph integration
│   ├── next/                 # Next.js components
│   ├── mcp/                  # MCP interface
│   └── utils/                # Shared utilities
├── test/                     # E2E tests
├── docs/                     # Documentation
├── scripts/                  # Build scripts
├── fixtures/                 # Test fixtures
├── turbo.json               # Turbo config
├── biome.json               # Biome config
└── package.json             # Root package

Key Architecture Patterns

  1. Monorepo Structure

    • Bun workspaces for package management
    • Turbo for build orchestration
    • Shared dependencies and tooling
    • Independent package versioning

  2. TypeScript-First Development

    • Strict TypeScript configuration
    • Type generation for GraphQL
    • Shared type definitions in utils
    • Runtime validation with Zod

  3. SDK Design Principles

    • Each package is independently usable
    • Minimal dependencies between packages
    • Consistent API design across packages
    • Comprehensive TypeScript types

  4. Platform Integration

    • GraphQL for API communication
    • RESTful endpoints where appropriate
    • WebSocket support for real-time data
    • Authentication and authorization built-in

Development Guidelines

TypeScript Conventions

  • NO default exports (except when framework requires)
  • Use import type for type imports
  • Prefer interfaces over type aliases for objects
  • Never use any - use unknown or proper types
  • Use discriminated unions for error handling
  • Naming conventions:
    • Files: kebab-case
    • Variables/functions: camelCase
    • Types/interfaces/classes: PascalCase
    • Constants: UPPER_SNAKE_CASE

Code Style Rules

  • Prefer nullish coalescing (??) over logical OR (||)
  • Use early returns to reduce nesting
  • Extract complex logic into well-named functions
  • Keep functions small and focused
  • Use structured logging with proper context

API Design Principles

  • RESTful conventions for HTTP endpoints
  • GraphQL for complex queries and subscriptions
  • Consistent error responses
  • Proper HTTP status codes
  • Comprehensive OpenAPI documentation

Blockchain Best Practices

  • Always validate addresses before use
  • Handle chain-specific differences properly
  • Implement proper gas estimation
  • Use type-safe contract interactions
  • Never store private keys in code or logs

Git Workflow

  • Never push to main branch
  • Branch naming: feat/, fix/, chore/, etc.
  • Commit format: type(scope): description
  • Create PRs for all changes
  • Ensure CI passes before merge

Claude Code Best Practices

  • Always read entire files before making changes
  • Run tests after modifications
  • Check existing patterns before implementing new features
  • Use the project's established error handling patterns
  • Validate all blockchain interactions
  • Keep security in mind - never expose sensitive data
  • Use queue jobs for long-running operations
  • Implement proper retry logic for external calls

Package-Specific Guidelines

SDK CLI (@settlemint/sdk-cli)

  • Main entry point for developers
  • Provides project scaffolding
  • Handles authentication flows
  • Manages deployments and configurations

SDK JS (@settlemint/sdk-js)

  • Core platform integration
  • API client for SettleMint services
  • Authentication and authorization
  • Resource management (nodes, networks, etc.)

SDK Portal (@settlemint/sdk-portal)

  • Smart contract portal integration
  • Contract deployment and verification
  • Transaction management
  • Event monitoring

SDK Viem (@settlemint/sdk-viem)

  • Viem-based blockchain interactions
  • Multi-chain support
  • Type-safe contract calls
  • Transaction helpers

Testing Guidelines

  • Write unit tests using Vitest
  • E2E tests for CLI commands
  • Mock external API calls
  • Test error scenarios
  • Use test fixtures for consistency
  • Follow AAA pattern (Arrange, Act, Assert)

Environment Configuration

Key environment variables:

  • SETTLEMINT_API_URL - Platform API endpoint
  • SETTLEMINT_AUTH_TOKEN - Authentication token
  • NODE_ENV - Environment (development/production)

Package-specific configs:

  • Each SDK package may have its own configuration
  • Check individual package README files
  • Use .env files for local development

Troubleshooting

Common Issues

  1. Build errors: Run bun install and bun run build
  2. Type errors: Check with bun run typecheck
  3. Linting issues: Fix with bun run lint:fix
  4. Test failures: Check test output and mocks

Development Tips

  • Use Turbo's cache for faster builds
  • Run specific package tests with filters
  • Check individual package README files
  • Use --verbose flag for detailed output

Before Creating a PR

  1. Run tests: bun test
  2. Type check: bun run typecheck
  3. Lint code: bun run lint
  4. Format code: bun run format
  5. Update documentation if needed
  6. Test locally with different scenarios

Project-Specific Notes

  • This is a developer SDK, not an application
  • Supports the SettleMint blockchain platform
  • Each package can be used independently
  • Follow semantic versioning for releases
  • Documentation is essential for all public APIs

Command Reference

Use these Claude Code commands when appropriate:

  • /pr - Create pull requests
  • /qa - Run quality checks
  • /explore - Understand architecture
  • /stuck - Debug systematically
  • /deps - Update dependencies safely
  • /performance - Analyze performance

MCP Server Usage

Linear (Project Management)

When working with Linear tickets, use the MCP Linear tools:

# Search for issues
mcp__linear__list_issues(query="ENG-3236", limit=10)

# Get issue details
mcp__linear__get_issue(id="ENG-3236")

# Update issue with comment and/or status
mcp__linear__update_issue(
  id="ENG-3236",
  stateId="<state-id>",  # Optional: update status
  description="Updated description"  # Optional: update description
)

# Create comment on issue
mcp__linear__create_comment(
  issueId="<issue-id>",
  body="PR created: https://github.com/..."
)

# List issue statuses to find stateId
mcp__linear__list_issue_statuses(teamId="<team-id>")

When you create a PR for a Linear ticket:

  1. Add a comment with the PR link using mcp__linear__create_comment
  2. Update the issue status if needed using mcp__linear__update_issue
  3. Include the Linear issue ID in the PR description for automatic linking

Sentry (Error Tracking)

Use Sentry MCP tools for error investigation:

# Find organizations you have access to
mcp__sentry__find_organizations()

# Find issues in an organization
mcp__sentry__find_issues(
  organizationSlug="settlemint",
  query="is:unresolved",
  sortBy="last_seen"
)

# Get detailed error information
mcp__sentry__get_issue_details(
  organizationSlug="settlemint",
  issueId="PROJECT-123"
)

# Update issue status
mcp__sentry__update_issue(
  organizationSlug="settlemint",
  issueId="PROJECT-123",
  status="resolved"
)

Context7 (Documentation)

Use for checking latest documentation:

# Search for library documentation
mcp__context7__resolve-library-id(libraryName="viem")

# Get library docs
mcp__context7__get-library-docs(
  context7CompatibleLibraryID="/wagmi-dev/viem",
  topic="contract-interactions"
)

DeepWiki (GitHub Documentation)

Use for repository documentation:

# Get repository documentation structure
mcp__deepwiki__read_wiki_structure(repoName="wagmi-dev/viem")

# Read repository documentation
mcp__deepwiki__read_wiki_contents(repoName="wagmi-dev/viem")

# Ask questions about a repository
mcp__deepwiki__ask_question(
  repoName="wagmi-dev/viem",
  question="How do I deploy a contract?"
)