.copilot-codeGeneration-instructions.md

Copilot Code Generation Instructions

Project Overview

This is the Moonlight SDK, a privacy-focused toolkit for blockchain development with special emphasis on Stellar Soroban smart contracts.

Core Collaboration Guidelines

• Suggest better abstractions that make implementation simpler and more readable
• Prioritize readability and understandability as this is an SDK
• Manage complexity carefully, especially for protocol-specific business rules
• Avoid code bloat and unnecessary functions
• When suggesting significant changes, provide reasoning and seek confirmation first
• Always explain the rationale behind implementation approaches
• Keep unit tests in the same directory as the features they test
• Aim for elegant solutions that balance simplicity with correctness
• When in doubt about adding complexity, ask and explain potential value

Code Style Guidelines

General

• Use TypeScript for all code files
• Include appropriate JSDoc comments for functions and classes
• Use meaningful variable and function names
• Follow a functional programming style where appropriate

Imports

• Always include file extensions in imports (e.g., .ts, .js)
• For Deno compatibility, use explicit file extensions in imports
• Order imports alphabetically: built-in modules, external dependencies, then local modules

TypeScript

• Use explicit typing rather than implicit where possible
• Use interfaces for object shapes
• Use type guards and assertions appropriately
• Prefer readonly properties when objects shouldn't be modified
• Use undefined over null when possible

Error Handling

• Use async/await with try/catch for asynchronous code
• Provide meaningful error messages
• Use custom error classes when appropriate

Testing

• Write tests for all functionality
• Use descriptive test names

Blockchain-specific

• Always validate inputs before sending to the blockchain
• Handle network errors gracefully
• Provide appropriate logging for transactions
• Use Buffer for binary data handling
• Follow cryptographic best practices

Architecture Patterns

• Use dependency injection where appropriate
• Separate concerns: data access, business logic, presentation
• Use factory patterns for object creation
• Keep modules small and focused

Documentation

• Include usage examples in JSDoc comments
• Document public APIs thoroughly
• Explain complex algorithms or business logic in comments

Deno-specific Guidelines

• Use Deno native APIs instead of Node.js APIs when possible
• Reference the deno.json import map for dependencies
• Ensure compatibility with Deno's permissions model
• Use TypeScript features fully supported by Deno

Moonlight SDK Specifics

• Follow the established pattern for UTXO-based privacy components
• Maintain consistent API patterns across the SDK
• When implementing cryptographic functions, prioritize security over performance
• Include proper input validation for all public-facing APIs