|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Essential Commands |
| 6 | + |
| 7 | +### Building and Development |
| 8 | +- `pnpm install` - Install workspace dependencies |
| 9 | +- `pnpm programs:build` - Build all Rust programs and fetch dependencies |
| 10 | +- `pnpm programs:test` - Run Rust program tests |
| 11 | +- `pnpm programs:debug` - Run Rust program tests with logs enabled |
| 12 | +- `pnpm clients:js:test` - Run JavaScript client tests |
| 13 | +- `pnpm clients:rust:test` - Run Rust client tests |
| 14 | +- `pnpm generate` - Generate IDLs and clients (shortcut for both commands below) |
| 15 | +- `pnpm generate:idls` - Generate IDLs from Rust programs using Shank |
| 16 | +- `pnpm generate:clients` - Generate client libraries using Kinobi |
| 17 | + |
| 18 | +### Testing and Quality |
| 19 | +- `pnpm lint` - Run linting for both JS client and Rust programs |
| 20 | +- `pnpm lint:fix` - Auto-fix linting issues and format code |
| 21 | +- `cd clients/js && pnpm test` - Run specific JS client tests |
| 22 | +- `cd clients/js && pnpm build` - Build JS client |
| 23 | +- `cargo test-bpf` - Run Rust program tests (from program directory) |
| 24 | +- `cargo build-bpf` - Build Rust program (from program directory) |
| 25 | + |
| 26 | +### Local Development |
| 27 | +- `pnpm validator` - Start local validator with program deployed |
| 28 | +- `pnpm validator:debug` - Start local validator with logs |
| 29 | +- `pnpm validator:stop` - Stop local validator |
| 30 | +- `pnpm validator:logs` - Show validator logs |
| 31 | + |
| 32 | +## Architecture Overview |
| 33 | + |
| 34 | +### Multi-Language Workspace Structure |
| 35 | +This repository contains both Rust programs and multiple client libraries: |
| 36 | +- **Rust Program**: `programs/mpl-core/` - The on-chain Solana program |
| 37 | +- **JavaScript Client**: `clients/js/` - Umi-compatible JS library |
| 38 | +- **Rust Client**: `clients/rust/` - Rust client library |
| 39 | +- **Python Client**: `clients/python/` - Python client (minimal) |
| 40 | + |
| 41 | +### Program Architecture (Rust) |
| 42 | +The core program follows a modular plugin-based architecture: |
| 43 | +- **State Management**: `state/` - Asset, Collection, and other core data structures |
| 44 | +- **Plugin System**: `plugins/` - Extensible plugin architecture with three categories: |
| 45 | + - `internal/authority_managed/` - Collection-level plugins (royalties, attributes, etc.) |
| 46 | + - `internal/owner_managed/` - Asset-level plugins (freeze, burn, transfer delegates) |
| 47 | + - `internal/permanent/` - Immutable plugins (edition, permanent delegates) |
| 48 | + - `external/` - External plugin adapters for third-party extensions |
| 49 | +- **Processors**: `processor/` - Instruction handlers for all program operations |
| 50 | +- **Instructions**: Core operations like create, transfer, burn, plugin management |
| 51 | + |
| 52 | +### Client Generation Workflow |
| 53 | +1. Rust program code defines the on-chain interface using Shank annotations |
| 54 | +2. `pnpm generate:idls` extracts IDL (Interface Definition Language) files |
| 55 | +3. `pnpm generate:clients` uses Kinobi to generate client code from IDLs |
| 56 | +4. Generated client code appears in `clients/js/src/generated/` |
| 57 | +5. Hand-written client code in `clients/js/src/` provides higher-level APIs |
| 58 | + |
| 59 | +### Key Plugin Types |
| 60 | +- **FreezeDelegate**: Allows freezing/unfreezing assets |
| 61 | +- **BurnDelegate**: Permits burning assets |
| 62 | +- **TransferDelegate**: Enables transfers on behalf of owner |
| 63 | +- **Royalties**: Collection-level royalty enforcement |
| 64 | +- **Attributes**: On-chain metadata storage |
| 65 | +- **MasterEdition**: Print/edition functionality |
| 66 | +- **External Adapters**: Third-party plugin integration (Oracle, AppData, etc.) |
| 67 | + |
| 68 | +## Development Patterns |
| 69 | + |
| 70 | +### Code Generation |
| 71 | +- Never edit files in `clients/js/src/generated/` - they are auto-generated |
| 72 | +- Run `pnpm generate` after making changes to Rust program interfaces |
| 73 | +- Use Kinobi visitors in `configs/kinobi.cjs` for client customization |
| 74 | + |
| 75 | +### Testing |
| 76 | +- Program tests are written in Rust using the standard test framework |
| 77 | +- Client tests use AVA framework and require a running validator |
| 78 | +- Tests often use generated keypairs and work with both individual assets and collections |
| 79 | + |
| 80 | +### Plugin Development |
| 81 | +- New internal plugins go in appropriate `plugins/internal/` subdirectory |
| 82 | +- External plugin adapters use the external plugin system |
| 83 | +- Plugins have distinct authority models (owner-managed vs authority-managed) |
| 84 | + |
| 85 | +### Asset Hierarchy |
| 86 | +- **Collections**: Optional grouping mechanism with shared plugins |
| 87 | +- **Assets**: Core NFT-like digital assets that can belong to collections |
| 88 | +- **Plugin Inheritance**: Assets inherit authority-managed plugins from their collection |
0 commit comments