From 3af30728e8787732a70af2c41f5cfc1784596233 Mon Sep 17 00:00:00 2001 From: jeffyanta Date: Fri, 5 Dec 2025 10:27:01 -0500 Subject: [PATCH] Setup Claude --- CLAUDE.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..bba0262 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,138 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Overview + +This is the Open Code Protocol (OCP) server monolith, a Go-based gRPC/web service system that powers next-generation currency launchpad and payment systems. It implements the first L2 solution on Solana using an intent-based system backed by a sequencer. + +## Commands + +### Testing +```bash +# Run all tests with coverage +make test + +# Run tests for a specific package +go test ./ocp/rpc/transaction/... + +# Run a single test +go test -run TestName ./path/to/package + +# Run tests with verbose output +go test -v ./... +``` + +### Building +This is a library project without a main entry point. Integration is done by importing packages into applications. + +## Architecture + +### Core System Components + +**Intent System & Sequencer** (`ocp/` package) +- The heart of the L2 solution lives in the `ocp/` package +- Intent-based transaction system: clients submit intents, sequencer processes them +- Key components: + - `ocp/rpc/`: gRPC service implementations (entry points for client requests) + - `ocp/worker/`: Background workers (nonce management, swap processing, sequencer, Geyser integration) + - `ocp/transaction/`: Transaction building and local nonce pool management + - `ocp/data/`: Data layer with Store interfaces for all domain entities + +**Data Layer Architecture** +- Pattern: Interface-based stores with multiple implementations (Postgres, in-memory) +- Each domain entity (account, intent, fulfillment, action, etc.) has: + - `ocp/data/{entity}/store.go`: Store interface definition + - `ocp/data/{entity}/postgres/`: Postgres implementation + - `ocp/data/{entity}/memory/`: In-memory implementation for tests + - `ocp/data/{entity}/tests/`: Shared test suite for all implementations +- `ocp/data/provider.go`: Aggregates all stores into a single Provider interface +- Provider composes three data sources: BlockchainData, DatabaseData, WebData + +**gRPC Application Framework** (`grpc/app/`) +- Standardized app lifecycle: Init -> RegisterWithGRPC -> Run -> Stop +- Apps implement the `App` interface with initialization, service registration, and shutdown +- Built-in features: New Relic integration, TLS support, health checks, pprof/expvar +- Interceptor chain: headers -> metrics -> validation -> min version checking +- Configuration via Viper (YAML files or environment variables) + +**Transaction & Intent Flow** +1. Client submits intent via `ocp/rpc/transaction/server.go` +2. Intent validated through antispam/AML guards +3. Sequencer worker (`ocp/worker/sequencer/`) processes intent +4. Actions scheduled and executed (intent_handler, action_handler, fulfillment_handler) +5. Transactions built using local nonce pools to avoid Solana RPC contention +6. Fulfillments committed and monitored + +**Solana Integration** +- `solana/` package: Low-level Solana primitives (accounts, transactions, programs) +- `solana/token/`: SPL Token program interface +- VM indexer client for tracking on-chain state changes +- Geyser worker (`ocp/worker/geyser/`) for real-time blockchain event streaming + +**Workers** +- All workers implement `Runtime` interface (Start method with interval) +- `ocp/worker/sequencer/`: Core sequencer logic (intent, action, fulfillment handlers) +- `ocp/worker/nonce/`: Nonce allocation and pool management +- `ocp/worker/swap/`: Token swap processing +- `ocp/worker/account/`: Account state synchronization +- `ocp/worker/geyser/`: Blockchain event streaming via Geyser + +### Key Patterns + +**Database Transactions** +- Use `database/postgres/db.go` utilities: `ExecuteTxWithinCtx` for transactions +- Automatic retry on serialization failures via `ExecuteRetryable` +- Context-based transaction passing (no explicit tx parameters) +- Default isolation: ReadCommitted + +**Testing** +- Shared test suites in `{package}/tests/tests.go` for interface conformance +- Postgres tests use `ory/dockertest` for containerized database setup +- `testutil/` provides shared test utilities (server mocking, VM utilities, wait helpers) +- In-memory implementations available for fast unit tests + +**Configuration** +- `config/` package: Interface-based config with env and memory providers +- App-level config in `grpc/app/config.go` (listen addresses, TLS, logging, New Relic) +- Service-specific config in respective packages (e.g., `ocp/rpc/transaction/config.go`) + +**Metrics & Observability** +- New Relic integration throughout (traces, logs, custom events) +- `metrics/` package: Constants, event tracking, tracing utilities +- Custom metrics in service packages (e.g., `ocp/rpc/transaction/metrics.go`) + +**Error Handling** +- Sentinel errors defined in store interfaces (e.g., `ErrAccountInfoNotFound`) +- Use `github.com/pkg/errors` for error wrapping with context +- gRPC error codes mapped appropriately in RPC handlers + +## API Contracts + +Protobuf definitions are in the separate [ocp-protobuf-api](https://github.com/code-payments/ocp-protobuf-api) repository. This project imports generated Go code from that repo. + +## Development Guidelines + +**When working with data stores:** +- Always check existing Store interface before adding new methods +- Implement for both Postgres and memory stores +- Add to shared test suite to ensure consistency +- Use context for cancellation, not timeouts + +**When adding new RPC methods:** +- Follow existing patterns in `ocp/rpc/transaction/server.go` +- Add metrics collection for the new endpoint +- Implement appropriate authentication via `ocp/auth/signature.go` +- Add antispam/AML checks if handling user funds + +**When working with Solana transactions:** +- Use `ocp/transaction/` package utilities for building transactions +- Leverage `LocalNoncePool` to avoid Solana nonce contention +- Always include proper signature verification +- Test with local simulation before blockchain submission + +**Worker development:** +- Implement `Runtime` interface from `ocp/worker/runtime.go` +- Use appropriate intervals based on task criticality +- Include proper context cancellation handling +- Add metrics for monitoring worker health