spark CLAUDE.md

Spark Repository

Spark is a Bitcoin Layer 2 protocol enabling instant, low-cost Bitcoin transactions using FROST threshold signatures. For deep protocol and architecture context, see .claude/CLAUDE.md.

Setup

mise trust && mise install
lefthook install  # git hooks (optional)

Components

• spark/ - Go backend (Signing Operators) - see spark/CLAUDE.md
• sdks/js/ - JavaScript/TypeScript SDK - see sdks/js/packages/spark-sdk/CLAUDE.md
• signer/ - Rust FROST signing implementation
• lrc20.dev/ - BTKN token layer (Rust)
• protos/ - Protocol buffer definitions

Code Quality Guidelines

Comments

Be judicious with comments. Prefer clear naming and well-structured functions over explanatory comments.

Avoid redundant comments:

// Bad - comment just repeats the code
// Verify operator signatures
verifyOperatorSignatures(sigs)

// Good - no comment needed, function name is clear
verifyOperatorSignatures(sigs)

When comments ARE useful:

• Non-obvious "why" explanations (e.g., race conditions, protocol requirements)
• Public API documentation
• Security-critical sections
• References to external specs or papers

Comment quality guidelines:

• Explain "why", not "what" - the code shows what happens; comments explain reasoning
• Comments must be self-contained - never reference "the old implementation" since future readers won't have that context
• Only add non-obvious information - // Save to database before db.Save() wastes space
• Don't comment out code - delete it; git remembers
• A Jira ticket belongs in a comment as TODO(SP-XXXX), or appended as a citation to a comment that already reads on its own - never as a bare "See SP-1234" standing in for the reason

Logging (Go)

We use Zap (go.uber.org/zap) for all logging, replacing log/slog from the standard library. Zap has two logger types:

• SugaredLogger — default for logs with dynamic values. Use printf-style formatting via logger.Sugar().
• Logger — use only when attaching approved, searchable attributes.