From 727f0312ea6ab8b3adf7833c9d70fe0897aca12e Mon Sep 17 00:00:00 2001 From: jeffyanta Date: Wed, 10 Jun 2026 09:31:18 -0400 Subject: [PATCH] Update Claude.md --- CLAUDE.md | 45 +++++++++++++++++++++++++++++++++------------ 1 file changed, 33 insertions(+), 12 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index bba0262..ca9620e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,13 +4,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## 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. +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. [Flipcash](https://flipcash.com) is the consumer wallet app built on this protocol. ## Commands ### Testing ```bash -# Run all tests with coverage +# Run all tests with coverage (same as CI) make test # Run tests for a specific package @@ -23,6 +23,8 @@ go test -run TestName ./path/to/package go test -v ./... ``` +Postgres store tests spin up containers via `ory/dockertest`, so Docker must be running for the full suite. + ### Building This is a library project without a main entry point. Integration is done by importing packages into applications. @@ -31,17 +33,21 @@ This is a library project without a main entry point. Integration is done by imp ### Core System Components **Intent System & Sequencer** (`ocp/` package) -- The heart of the L2 solution lives in the `ocp/` package +- The heart of the L2 solution lives in the `ocp/` package; all other top-level packages are generic libraries and utilities - 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/rpc/`: gRPC service implementations (entry points for client requests): `transaction`, `account`, `currency`, `messaging` + - `ocp/worker/`: Background workers (nonce management, swap processing, sequencer, Geyser integration, account sync, currency tasks) - `ocp/transaction/`: Transaction building and local nonce pool management - `ocp/data/`: Data layer with Store interfaces for all domain entities + - `ocp/integration/`: Pluggable integration hooks (SubmitIntent, Swap, Geyser, Moderation, Antispam) for application-specific behavior + - `ocp/antispam/`, `ocp/aml/`: Guards applied to intents that handle user funds + - `ocp/common/`: Shared domain utilities (Account abstraction, VM helpers) + - `ocp/vm/`: Virtual account utilities for the Code VM **Data Layer Architecture** - Pattern: Interface-based stores with multiple implementations (Postgres, in-memory) -- Each domain entity (account, intent, fulfillment, action, etc.) has: +- Each domain entity (account, intent, fulfillment, action, deposit, swap, nonce, timelock, vault, vm, 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 @@ -58,25 +64,40 @@ This is a library project without a main entry point. Integration is done by imp **Transaction & Intent Flow** 1. Client submits intent via `ocp/rpc/transaction/server.go` -2. Intent validated through antispam/AML guards +2. Intent validated through antispam/AML guards and integration hooks 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 +**Swap & Deposit Subsystem** +- USDC is the external on/off-ramp currency; USDF is the core mint used internally (constants in `usdc/` and `usdf/`) +- External USDC deposits are detected by the Geyser worker (`ocp/worker/geyser/external_deposit.go`), tracked in the `ocp/data/deposit/` store, and swapped into USDF +- Swaps come in two flavors: stateful swaps processed by `ocp/worker/swap/`, and stateless swaps handled directly in `ocp/rpc/transaction/stateless_swap.go` +- `solana/coinbasestableswapper/`: Solana program interface for Coinbase's Stable Swapper (used for USDC↔USDF) +- `coinbase/`: HTTP client for the Coinbase Developer Platform Onramp API (JWT auth, used as a swap funding source) + **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 +- VM indexer client (`code-vm-indexer` dependency) for tracking on-chain VM state changes - Geyser worker (`ocp/worker/geyser/`) for real-time blockchain event streaming **Workers** -- All workers implement `Runtime` interface (Start method with interval) +- All workers implement `Runtime` interface (Start method with interval) from `ocp/worker/runtime.go` - `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/swap/`: Token swap processing (including auto-recovery when swaps fail) - `ocp/worker/account/`: Account state synchronization -- `ocp/worker/geyser/`: Blockchain event streaming via Geyser +- `ocp/worker/currency/`: Currency-related background tasks +- `ocp/worker/geyser/`: Blockchain event streaming via Geyser (external deposits, currency reserves, timelock state) + +**Utility Packages** (top level) +- `cache/`: In-memory cache with weighted budget management +- `currency/`: Exchange rate client interface (`coingecko/` implementation) +- `retry/`: Configurable retrier with backoff strategies +- `sync/`: Consistent hash ring +- `pointer/`, `protoutil/`, `netutil/`, `osutil/`: Small helpers (pointers, proto comparison/streaming, outbound IP, container-aware memory limits) ### Key Patterns @@ -89,7 +110,7 @@ This is a library project without a main entry point. Integration is done by imp **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) +- `testutil/` provides shared test utilities (account/currency mocks, server mocking, VM utilities, wait helpers) - In-memory implementations available for fast unit tests **Configuration**