From 0e5268153cc021e7e6f8187041b0bb7143a8260a Mon Sep 17 00:00:00 2001
From: Dan Notestein <dan@syncad.com>
Date: Tue, 30 Dec 2025 00:55:58 -0500
Subject: [PATCH] Add CLAUDE.md for AI-assisted development

---
 CLAUDE.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..4afc10c2
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,92 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**hiveio-schemas** is a Python library for validating and serializing Hive blockchain JSON data structures. It provides msgspec-based schema definitions for all Hive blockchain operations, API responses, and transactions.
+
+## Development Commands
+
+```bash
+# Install dependencies
+poetry install
+
+# Run all tests
+poetry run pytest tests/
+
+# Run a specific test file
+poetry run pytest tests/test_hive_fields.py
+
+# Run tests with verbose output
+poetry run pytest tests/ -v
+
+# Type checking
+poetry run mypy schemas/ tests/
+
+# Linting (with auto-fix)
+poetry run ruff check --fix schemas/ tests/
+
+# Format code
+poetry run ruff format schemas/ tests/
+
+# Run pre-commit hooks (includes ruff, mypy, poetry-lock check)
+poetry run pre-commit run --all-files
+```
+
+## Architecture
+
+### Core Classes
+
+**`PreconfiguredBaseModel`** (`schemas/_preconfigured_base_model.py`):
+- Base class for all schema types, extends `msgspec.Struct`
+- Provides `dict()`, `json()`, `parse_raw()`, `parse_file()`, `parse_builtins()` methods
+- Handles automatic type swapping in `__post_init__` for special Hive types
+- Supports dictionary-like access via `__getitem__`/`__setitem__`
+
+**Serialization Formats**:
+- **HF26** (current): NAI-based asset format `{"amount": "1000", "precision": 3, "nai": "@@000000021"}`
+- **Legacy**: String-based asset format `"1.000 HIVE"`
+
+### Key Modules
+
+- **`schemas/operations/`**: All blockchain operations (transfer, vote, comment, etc.)
+  - Each operation has its own file plus representation types in `representation_types.py`
+  - Virtual operations are in `virtual/` subdirectory
+- **`schemas/apis/`**: Response schemas for each Hive API (database_api, condenser_api, etc.)
+- **`schemas/fields/`**: Custom field types (assets, AccountName, PublicKey, HiveDateTime, etc.)
+- **`schemas/jsonrpc.py`**: JSON-RPC request/response handling with `get_response_model()`
+- **`schemas/decoders.py`**: Decoding hooks for HF26 and legacy formats
+- **`schemas/encoders.py`**: Encoding hooks for serialization
+- **`schemas/policies/`**: Runtime policies for extra fields, testnet assets, etc.
+
+### Custom Field Types
+
+Defined in `schemas/fields/`:
+- **Assets**: `AssetHive`, `AssetHbd`, `AssetVests` with NAI and legacy parsing
+- **Validators**: `AccountName`, `PublicKey`, `Permlink` with regex constraints
+- **Integers**: `HiveInt`, `Uint16t`, `Uint32t`, `Int64t`, `Uint64t`
+- **Compound**: `HiveDateTime`, `Signature`, `TransactionId`
+
+### Operation Representations
+
+Operations have two forms:
+- **Raw operations**: e.g., `TransferOperation` - the operation data itself
+- **Representations**: Wrappers with `type` and `value` fields for HF26/Legacy serialization
+  - `HF26RepresentationTransferOperation` wraps `TransferOperation` with `type="transfer_operation"`
+  - `LegacyRepresentationTransferOperation` uses array format `["transfer", {...}]`
+
+### Testing Pattern
+
+Tests validate round-trip serialization:
+```python
+verify_serialization_and_deserialization(
+    schema=ResponseSchema,
+    parameters={"jsonrpc": "2.0", "result": {...}, "id": 1},
+    serialization_type="hf26"  # or "legacy"
+)
+```
+
+## Python Version
+
+Requires Python 3.12+. CI runs on Python 3.14.
-- 
GitLab