@curvhex/orm 0.1.0

package/LICENSE

@@ -0,0 +1,143 @@
+Apache License 2.0 with Commons Clause
+
+"Commons Clause" License Condition v1.0
+
+The Software is provided to you by the Licensor under the License, as defined
+below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights under
+the License will not include, and the License does not grant to you, the right
+to Sell the Software.
+
+For purposes of the foregoing, "Sell" means practicing any or all of the
+rights granted to you under the License to provide to third parties, for a fee
+or other consideration (including without limitation fees for hosting or
+consulting / support services related to the Software), a product or service
+whose value derives, entirely or substantially, from the functionality of the
+Software. Any license notice or attribution required by the License must also
+include this Commons Clause License Condition notice.
+
+Software: curvhex-orm
+License: Apache 2.0
+Licensor: Bugra Okumus
+
+---
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included
+      in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other
+      transformations represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works of the Work, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright
+      owner or by an individual or Legal Entity authorized to submit on
+      behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, use, sell, offer for sale, import, and
+      otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file, You must include a
+          readable copy of the attribution notices contained within such
+          NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law, shall any Contributor be liable
+      to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer
+      additional warranty, liability, or other obligations consistent
+      with this License. However, in accepting such obligations, You may
+      act only on Your own behalf and on Your sole responsibility.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Bugra Okumus
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0

package/README.md

@@ -0,0 +1,485 @@
+# Curvhex ORM
+
+TypeScript ORM for Solana PDA accounts. Query, filter, and aggregate on-chain data with a familiar API — inspired by Prisma, built for Solana.
+
+```typescript
+const users = await orm.models.userAccount.findMany({
+  where:   { authority: wallet.publicKey, isActive: true },
+  orderBy: { balance: 'desc' },
+  take:    10,
+})
+```
+
+---
+
+## The Problem
+
+Solana stores program state in accounts (PDAs). Querying them is painful:
+
+- `getProgramAccounts` only supports exact byte matching (`memcmp`)
+- No range queries, sorting, aggregation, or relations at the RPC level
+- Every project reimplements the same deserialization + filtering boilerplate
+- Switching from a public RPC to an indexer (Helius, your own Postgres) requires rewriting query logic
+
+Curvhex ORM solves this with a single, adapter-agnostic query API.
+
+---
+
+## How It Works
+
+```
+Your Code  →  CurvhexORM  →  QueryAdapter  →  Data Source
+                                ├── RpcAdapter       (getProgramAccounts)
+                                ├── HeliusAdapter    (DAS API)        [soon]
+                                └── PostgresAdapter  (your indexer)   [soon]
+```
+
+Define your schema once. Write queries once. Swap the adapter as your needs grow — from a quick prototype on public RPC to a production indexer — without changing a single query.
+
+---
+
+## Installation
+
+```bash
+npm install curvhex-orm @solana/web3.js
+```
+
+---
+
+## Quick Start
+
+### 1. Define your schema
+
+```typescript
+import { defineModel, anchor } from 'curvhex-orm'
+
+const UserAccount = defineModel({
+  // Anchor programs: use anchor() helper
+  discriminator: anchor('UserAccount'),
+
+  // Native programs: provide raw bytes
+  // discriminator: [1, 2, 3, 4, 5, 6, 7, 8],
+
+  fields: {
+    authority: { type: 'publicKey' },
+    balance:   { type: 'u64' },
+    tier:      { type: 'u8' },
+    isActive:  { type: 'bool' },
+    name:      { type: 'string' },
+  }
+})
+```
+
+Field offsets are calculated automatically from the discriminator length and field order — no manual byte counting.
+
+### 2. Create the ORM
+
+```typescript
+import { CurvhexORM, RpcAdapter } from 'curvhex-orm'
+import { Connection, PublicKey } from '@solana/web3.js'
+
+const connection = new Connection('https://api.mainnet-beta.solana.com')
+
+const orm = new CurvhexORM({
+  connection,
+  programId: 'YOUR_PROGRAM_ID',
+  models: { UserAccount },
+})
+```
+
+### 3. Query
+
+```typescript
+// Find by PDA seeds
+const user = await orm.models.userAccount.findByPda([
+  Buffer.from('user'),
+  wallet.publicKey.toBuffer(),
+])
+
+// Find by address
+const user = await orm.models.userAccount.findByAddress('Abc123...')
+
+// Find many with filters
+const users = await orm.models.userAccount.findMany({
+  where:   { isActive: true, authority: wallet.publicKey.toBase58() },
+  orderBy: { balance: 'desc' },
+  take:    20,
+  skip:    0,
+})
+```
+
+---
+
+## API Reference
+
+### `defineModel(input)`
+
+Defines an account schema. Offsets are computed automatically.
+
+```typescript
+const MyAccount = defineModel({
+  discriminator: anchor('MyAccount'), // or raw number[]
+  fields: {
+    owner:   { type: 'publicKey' },
+    amount:  { type: 'u64' },
+    enabled: { type: 'bool' },
+  }
+})
+```
+
+**Supported field types:**
+
+| Type | Size | TypeScript type |
+|------|------|-----------------|
+| `u8` `u16` `u32` | 1–4 bytes | `number` |
+| `i8` `i16` `i32` | 1–4 bytes | `number` |
+| `u64` `u128` | 8–16 bytes | `bigint` |
+| `i64` `i128` | 8–16 bytes | `bigint` |
+| `bool` | 1 byte | `boolean` |
+| `publicKey` | 32 bytes | `string` (base58) |
+| `string` | 4 + N bytes | `string` |
+| `bytes` | 4 + N bytes | `string` (hex) |
+
+### `anchor(name)`
+
+Computes the 8-byte Anchor discriminator for an account name.
+
+```typescript
+import { anchor } from 'curvhex-orm'
+
+anchor('UserAccount') // → [149, 88, 201, ...]
+```
+
+### `findMany(options?)`
+
+```typescript
+const results = await orm.models.userAccount.findMany({
+  where: {
+    // Equality (on-chain memcmp — fast)
+    authority: 'Abc123...',
+    isActive:  true,
+    tier:      2,
+
+    // Range operators (client-side filter)
+    balance: { gte: 100n, lte: 10_000n },
+    balance: { gt: 0n },
+    tier:    { in: [1, 2, 3] },
+    balance: { between: [100n, 1000n] },
+    tier:    { not: 0 },
+  },
+  orderBy: { balance: 'desc' },
+  take:    10,
+  skip:    0,
+  dataSize: 165, // optional: filter by account byte size
+})
+```
+
+> **On-chain vs client-side:** Equality filters (`authority`, `isActive`, `tier`) are sent as `memcmp` filters to the RPC node — only matching accounts are transferred. Range operators (`gt`, `gte`, `lt`, `lte`, `between`, `in`) are applied after accounts are received. Combine both for best performance.
+
+### `findFirst(options?)`
+
+Returns the first matching account or `null`.
+
+```typescript
+const user = await orm.models.userAccount.findFirst({
+  where: { authority: wallet.publicKey.toBase58() }
+})
+```
+
+### `findByAddress(address)`
+
+Fetches a single account by its public key string.
+
+```typescript
+const user = await orm.models.userAccount.findByAddress('Abc123...')
+```
+
+### `findByPda(seeds)`
+
+Derives the PDA and fetches the account.
+
+```typescript
+const user = await orm.models.userAccount.findByPda([
+  Buffer.from('user'),
+  wallet.publicKey.toBuffer(),
+])
+```
+
+### `count(where?)`
+
+```typescript
+const total = await orm.models.userAccount.count({ isActive: true })
+```
+
+### `aggregate(options)`
+
+```typescript
+const stats = await orm.models.userAccount.aggregate({
+  where:  { isActive: true },
+  _count: true,
+  _sum:   { balance: true },
+  _avg:   { balance: true },
+  _min:   { balance: true },
+  _max:   { balance: true },
+})
+// → { _count: 142, _sum: { balance: 5_000_000n }, _avg: ..., _min: ..., _max: ... }
+```
+
+### `groupBy(options)`
+
+```typescript
+const byTier = await orm.models.userAccount.groupBy({
+  by:    ['tier'],
+  where: { isActive: true },
+  _count: true,
+  _sum:  { balance: true },
+})
+// → [
+//     { tier: 2, _count: 40,  _sum: { balance: 2_000_000n } },
+//     { tier: 1, _count: 102, _sum: { balance: 3_000_000n } },
+//   ]
+```
+
+### `findMany` with `include` (Relations)
+
+Fetch related accounts in a single call. Deduplicates addresses automatically — if 100 vaults share the same owner, the owner account is fetched once.
+
+```typescript
+const VaultAccount = defineModel({
+  discriminator: anchor('VaultAccount'),
+  fields: {
+    ownerPubkey: { type: 'publicKey' },
+    totalLocked: { type: 'u64' },
+  }
+})
+
+const vaults = await orm.models.vaultAccount.findMany({
+  where: { totalLocked: { gt: 1000n } },
+  include: {
+    owner: {
+      model:      UserAccount,
+      foreignKey: 'ownerPubkey',
+    }
+  }
+})
+// → [{ address, totalLocked, owner: { authority, balance, tier } }]
+```
+
+---
+
+## Adapters
+
+The query API is adapter-agnostic. Swap the data source without changing your queries.
+
+### RpcAdapter (default)
+
+Works with any Solana RPC endpoint. No setup required.
+
+```typescript
+import { CurvhexORM, RpcAdapter } from 'curvhex-orm'
+
+const orm = new CurvhexORM({
+  connection,
+  programId: 'YOUR_PROGRAM_ID',
+  models:    { UserAccount },
+  // adapter defaults to RpcAdapter
+})
+```
+
+**Limitations:** `getProgramAccounts` is rate-limited or blocked on many public endpoints for large programs. Range queries require fetching all matching accounts first.
+
+### HeliusAdapter *(coming soon)*
+
+Uses the Helius DAS API. Faster, higher rate limits, better support for large programs.
+
+```typescript
+import { HeliusAdapter } from 'curvhex-orm/adapters'
+
+const orm = new CurvhexORM({
+  connection,
+  programId: 'YOUR_PROGRAM_ID',
+  models:    { UserAccount },
+  adapter:   new HeliusAdapter({ apiKey: 'your-helius-key' }),
+})
+```
+
+### PostgresAdapter *(coming soon)*
+
+Query your own Geyser-indexed database. Enables true range queries, sorting, and aggregation at the database level.
+
+```typescript
+import { PostgresAdapter } from 'curvhex-orm/adapters'
+
+const orm = new CurvhexORM({
+  connection,
+  programId: 'YOUR_PROGRAM_ID',
+  models:    { UserAccount },
+  adapter:   new PostgresAdapter({
+    connectionString: 'postgresql://user:pass@localhost:5432/mydb',
+    table:            'user_accounts',
+  }),
+})
+```
+
+---
+
+## Architecture
+
+### Why adapters?
+
+Solana's native RPC (`getProgramAccounts`) only supports exact byte matching. Range queries, sorting, and aggregation require off-chain infrastructure.
+
+Rather than picking one solution, Curvhex ORM abstracts the data source:
+
+```
+findMany({ where: { balance: { gt: 100n } } })
+  │
+  ├── RpcAdapter       → fetch all + client-side filter
+  ├── HeliusAdapter    → Helius API query
+  └── PostgresAdapter  → SELECT * WHERE balance > 100
+```
+
+As the Solana ecosystem matures (Triton's RPC 2.0, indexers), adapters can be upgraded independently.
+
+### On-chain vs off-chain filtering
+
+| Filter type | RpcAdapter | HeliusAdapter | PostgresAdapter |
+|-------------|-----------|---------------|-----------------|
+| Equality (`authority = X`) | ✅ on-chain memcmp | ✅ | ✅ |
+| Range (`balance > 100`) | ⚠️ client-side | ✅ | ✅ |
+| Sorting | ⚠️ client-side | ✅ | ✅ |
+| Aggregation | ⚠️ client-side | partial | ✅ |
+| Relations (`include`) | ⚠️ N+1 fetches | ⚠️ N+1 fetches | ✅ JOIN |
+
+### Data consistency
+
+When using off-chain adapters (Helius, Postgres), there is an inherent indexer lag of 1–2 slots (~400–800ms). For critical reads (balance checks before transactions), use `findByAddress` or `findByPda` which always hit the RPC directly.
+
+---
+
+## Roadmap
+
+- [x] Schema definition with automatic offset calculation
+- [x] Borsh deserialization (all primitive types)
+- [x] `findMany` — memcmp filters + client-side range operators
+- [x] `findFirst`, `findByAddress`, `findByPda`
+- [x] `count`, `aggregate`, `groupBy`
+- [x] `include` — relation loading with deduplication
+- [x] Anchor discriminator helper (`anchor()`)
+- [x] Adapter pattern (`QueryAdapter` interface)
+- [x] `RpcAdapter`
+- [ ] `HeliusAdapter`
+- [ ] `PostgresAdapter` + Geyser sync guide
+- [ ] Cursor-based pagination
+- [ ] WebSocket subscriptions (`watch`)
+- [ ] Enum field support
+- [ ] Option<T> field support
+- [ ] Vec<T> field support
+- [ ] CLI: generate schema from IDL
+- [ ] RPC 2.0 adapter (Triton)
+
+---
+
+## Contributing
+
+Contributions are welcome. Here's how to get started:
+
+### Setup
+
+```bash
+git clone https://github.com/your-username/curvhex-orm
+cd curvhex-orm
+npm install
+```
+
+### Project structure
+
+```
+src/
+├── core/
+│   ├── types.ts          — field types, ModelDefinition, InferModel
+│   ├── schema.ts         — defineModel, anchor(), offset calculation
+│   ├── deserializer.ts   — Buffer → TypeScript object
+│   └── filters.ts        — memcmp builder, client-side filter logic
+├── adapters/
+│   ├── abstract/
+│   │   └── QueryAdapter.ts   — adapter interface
+│   └── RpcAdapter.ts         — getProgramAccounts implementation
+├── client/
+│   ├── CurvhexClient.ts   — findMany, findFirst, aggregate, groupBy, include
+│   └── CurvhexORM.ts      — entry point, wires models to adapter
+└── __tests__/
+    └── integration.test.ts
+```
+
+### Where to contribute
+
+Good first issues:
+
+- **`HeliusAdapter`** — implement `QueryAdapter` using the Helius DAS API
+- **`PostgresAdapter`** — implement `QueryAdapter` using `pg` or `postgres` client
+- **`Vec<T>` field support** — extend `FieldType` and the deserializer
+- **`Option<T>` field support** — handle Borsh option prefix byte
+- **Enum fields** — map `u8` values to string variants via schema
+- **Cursor-based pagination** — add `cursor` to `FindManyOptions`
+- **`watch()`** — WebSocket subscription wrapping `onAccountChange`
+
+### Implementing a new adapter
+
+Create a file under `src/adapters/` and implement the `QueryAdapter` interface:
+
+```typescript
+import { QueryAdapter, FindManyOptions } from './abstract/QueryAdapter'
+import { ModelDefinition, InferModel } from '../core/types'
+
+export class MyAdapter implements QueryAdapter {
+  async findMany<M extends ModelDefinition>(
+    model: M,
+    options: FindManyOptions<M>
+  ): Promise<InferModel<M>[]> {
+    // your implementation
+  }
+
+  async findByAddress<M extends ModelDefinition>(
+    model: M,
+    address: string
+  ): Promise<InferModel<M> | null> {
+    // your implementation
+  }
+
+  async findByPda<M extends ModelDefinition>(
+    model: M,
+    seeds: (Buffer | Uint8Array)[]
+  ): Promise<InferModel<M> | null> {
+    // your implementation
+  }
+}
+```
+
+Then export it from `src/index.ts` and add a test case to `integration.test.ts`.
+
+### Before submitting a PR
+
+```bash
+npx tsc --noEmit                          # type check
+npx tsx src/__tests__/integration.test.ts # run tests
+```
+
+All 8 integration test cases must pass. If you're adding a new adapter, add at least `findByAddress` and `findMany` test cases using a mock or a real endpoint.
+
+### Commit style
+
+```
+feat: add HeliusAdapter
+fix: handle empty discriminator in buildFilters
+docs: add Vec<T> field type to README
+```
+
+---
+
+## License
+
+Apache 2.0 with Commons Clause.
+
+Free to use in your own projects. You may not sell this software or offer it as a hosted service without a commercial license.
+

package/dist/adapters/RpcAdapter.d.ts

@@ -0,0 +1,12 @@
+import { Connection, PublicKey } from '@solana/web3.js';
+import { ModelDefinition, InferModel } from '../core/types';
+import { QueryAdapter, FindManyOptions } from './abstract/QueryAdapter';
+export declare class RpcAdapter implements QueryAdapter {
+    private connection;
+    private programId;
+    constructor(connection: Connection, programId: PublicKey);
+    findMany<M extends ModelDefinition>(model: M, options?: FindManyOptions<M>): Promise<InferModel<M>[]>;
+    findByAddress<M extends ModelDefinition>(model: M, address: string): Promise<InferModel<M> | null>;
+    findByPda<M extends ModelDefinition>(model: M, seeds: (Buffer | Uint8Array)[]): Promise<InferModel<M> | null>;
+}
+//# sourceMappingURL=RpcAdapter.d.ts.map

package/dist/adapters/RpcAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RpcAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/RpcAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAA4B,MAAM,iBAAiB,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG5D,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAExE,qBAAa,UAAW,YAAW,YAAY;IAEvC,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,SAAS;gBADT,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS;IAG1B,QAAQ,CAAC,CAAC,SAAS,eAAe,EACpC,KAAK,EAAE,CAAC,EACR,OAAO,GAAE,eAAe,CAAC,CAAC,CAAM,GACjC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IA2CrB,aAAa,CAAC,CAAC,SAAS,eAAe,EACzC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAO1B,SAAS,CAAC,CAAC,SAAS,eAAe,EACrC,KAAK,EAAE,CAAC,EACR,KAAK,EAAE,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,GAC/B,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CAMnC"}