docs: spec create_fund and Anchor essentials#6
Conversation
WalkthroughThis PR establishes project-wide documentation baseline by updating agent guidance to define feature development workflow, introducing a comprehensive Anchor framework reference, and documenting the fund program specification. All changes are documentation-only with no code or public API alterations. ChangesDocumentation and specification baseline
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
AGENTS.md (1)
1-1:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix the document title to match the filename.
The file is named
AGENTS.mdbut the title still saysCLAUDE.md. This inconsistency will confuse readers who reference the file.📝 Proposed fix
-# CLAUDE.md +# AGENTS.md🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@AGENTS.md` at line 1, The document title currently reads "CLAUDE.md" but the file is named AGENTS.md; update the top-level header text from "CLAUDE.md" to "AGENTS.md" (replace the existing header string) so the visible title matches the filename and prevents confusion; ensure the change is made in the file's first line/header.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@AGENTS.md`:
- Around line 218-225: The `@docs/anchor.md` path is ambiguous to readers;
update the text around the reference to either (a) replace `@docs/anchor.md`
with a standard relative path like `docs/anchor.md`, or (b) keep
`@docs/anchor.md` but add a short parenthetical explaining the `@` prefix (e.g.,
"the `@` prefix denotes the project docs directory") so callers of the `Anchor
framework` section and references to macros like `declare_id!`, `#[program]`,
`#[derive(Accounts)]`, and `#[account]` clearly understand where to find the
referenced file.
In `@docs/anchor.md`:
- Around line 46-74: Add a short note under the `#[account(...)]` constraints
table explaining that constraint evaluation order can matter and that some
constraints have implicit ordering requirements (e.g., `init` must appear before
`payer` and `space`, `init_if_needed` has special semantics), and mention that
constraints are evaluated in the order written; reference the `#[account(...)]`
attribute and specific examples like `init`, `payer`, `space`, `init_if_needed`,
and `seeds = [...], bump` (and `ctx.bumps`) so readers can locate the guidance
near the existing constraint table.
In `@programs/fund/SPEC.md`:
- Around line 104-105: The SPEC currently rejects `management_fee_bps` or
`performance_fee_bps` values greater than `10_000` (100%) without justification;
either add a short design note in SPEC.md explaining the business rationale for
the 100% cap (e.g., "manager cannot extract more than 100% of gains/AUM per
period, preventing negative investor returns or circular accounting") or
refactor the rule to reference a named compile-time constant (e.g., FEE_BPS_MAX
= 10_000) with an inline comment explaining why that value was chosen so future
reviewers see the constraint and can change it if needed; update the text around
`management_fee_bps`, `performance_fee_bps`, and `10_000` to point to the
justification or constant.
- Around line 29-38: The spec records management_fee_bps, performance_fee_bps,
capacity, and withdrawal_delay_days on Fund creation but doesn't explain why
immutable values are captured before those features exist; add a short "Design
rationale" subsection under the Fund parameters that (1) explicitly states
whether all fund parameters are intended to be immutable and why (e.g., LP
guarantees, anti-rug protections, on-chain auditability), (2) explains why each
recorded field must be set at creation rather than later (or call out which can
be deferred), and (3) documents any future enforcement plans referenced by
create_fund/Deposit/Withdraw instructions so readers understand the
forward-coupling; reference the Fund parameter names (management_fee_bps,
performance_fee_bps, capacity, withdrawal_delay_days) and the create_fund
behavior when writing the rationale.
- Around line 77-80: Add a brief rationale explaining why canonical zero-padding
is required for `name: [u8; 32]` (part of the Fund PDA seeds): state that the
rule ("no non-zero byte after the first zero") prevents different on‑chain byte
encodings that render to the same human‑readable name (e.g., "foo" vs
"foo\0\x01") from producing distinct PDAs, which could enable collision attacks
and confuse users/frontends; reference the `name: [u8; 32]` field and the Fund
PDA seeds when adding this explanation.
- Line 53: The spec and tests reference a create_fund instruction but the
program exposes initialize/Initialize; fix by aligning names—either add a thin
wrapper instruction/function named create_fund that calls the existing
initialize handler (e.g., export a public create_fund processor that delegates
to initialize/Initialize), or update the SPEC.md and any tests to call
initialize/Initialize; target the instruction entrypoint in
programs/fund/src/lib.rs and the instruction implementation in
programs/fund/src/instructions.rs (and update tests) so the public API and
documentation use the same identifier.
---
Outside diff comments:
In `@AGENTS.md`:
- Line 1: The document title currently reads "CLAUDE.md" but the file is named
AGENTS.md; update the top-level header text from "CLAUDE.md" to "AGENTS.md"
(replace the existing header string) so the visible title matches the filename
and prevents confusion; ensure the change is made in the file's first
line/header.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 241153a1-e3cb-4dcc-9631-fb2ad94eb41e
📒 Files selected for processing (3)
AGENTS.mddocs/anchor.mdprograms/fund/SPEC.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (3)
**/*.md
⚙️ CodeRabbit configuration file
Focus on the contents of the docs and not on cosmetic things like markdown formatting. We use markdown files for various docs including but not limited to the north star system specification, SPEC.md, the plan for how to get there, ROADMAP.md, guidelines for AI contributors, AGENTS.md, project overview and instructions for human contributors, README.md. Think about the target audience of a document when deciding what comment to leave. For specifications and designs, suggest potential product, architectural, and UI/UX improvements. For plans, suggest changes that would make things more parallelizable and deliverable-focused. For instructions, suggest better rules and guidelines and point out missing instructions. In all cases, flag needless bloat, prefer clear concise writing, and consider the structure of the document and order of the sections
Files:
docs/anchor.mdAGENTS.mdprograms/fund/SPEC.md
*
⚙️ CodeRabbit configuration file
Focus on providing constructive criticism. Whenever you see a suboptimal approach, suggest more idiomatic or robust alternative(s). Flag potential footguns. Suggest FP alternatives to mutable/imperative code. Point out architectural flaws like leaky abstractions, tight coupling, wrong level of abstraction, poor type modeling, over-abstraction, unclear domain boundaries. Code should generally be organized based on business concerns rather than technical aspects - suggest improvements if you find violations. Point out gaps in test coverage but suggest tests that are not too coupled to the implementation and actually test domain invariants and business logic.
Files:
AGENTS.md
programs/fund/SPEC.md
📄 CodeRabbit inference engine (AGENTS.md)
Keep feature specs in
programs/fund/SPEC.mdincremental — only introduce concepts the current feature needs; list everything else under 'Not yet specified'. Call out non-obvious design choices (share-burn timing, fee accrual model, etc.) explicitly
Files:
programs/fund/SPEC.md
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-06T17:37:24.032Z
Learning: Documentation for notes, learnings, conventions, rationale, and rules must belong in tracked markdown files (this file, `programs/fund/README.md`, `programs/fund/SPEC.md`, ADRs under `adrs/`, or a dedicated doc), not in agent memory, scratchpads, or `.tmp/` files
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-06T17:37:24.032Z
Learning: Non-trivial shell logic (more than ~3 lines, commands with non-obvious quoting/escaping, or one-shot probes that might be useful again) must live in `./scripts/<name>.nu` with a paired `./scripts/<name>.test.nu`, and the test suite must run as part of the script's nix derivation (`checkPhase`)
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-06T17:37:24.032Z
Learning: Every new feature of the on-chain program must follow the feature workflow: (1) spec the feature in `programs/fund/SPEC.md`, (2) update the interface in Rust types/account structs/instruction handler signatures (stub implementation), (3) write a failing integration test in `programs/fund/tests/*.rs`, (4) implement the handler body until the test passes, (5) confirm the test passes and run `cargo test --workspace`, (6) commit and push
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-06T17:37:24.032Z
Learning: `anchor build` must run before `cargo test` because integration tests require `target/deploy/fund.so` to compile
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-06T17:37:24.032Z
Learning: When adding a new instruction, create `programs/fund/src/instructions/<name>.rs` with `#[derive(Accounts)] pub struct <Name>` and `pub fn handler(...)`, then add `pub mod <name>; pub use <name>::*;` to `instructions.rs`, and add a thin wrapper inside `#[program] mod fund` in `lib.rs`
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-06T17:37:24.032Z
Learning: Read docs/anchor.md before modifying `programs/fund/src/` to understand the four core macros (`declare_id!`, `#[program]`, `#[derive(Accounts)]`, `#[account]`), account validation, the 8-byte discriminator, and the IDL/client codegen flow
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-06T17:37:24.032Z
Learning: Every new instruction must be reviewed against the Solana/Anchor attack catalogue in docs/sealevel-attacks.md before merging; each `#[derive(Accounts)]` struct must be explicitly walked through the security checklist
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-06T17:37:24.032Z
Learning: Always succumb to whatever Solana tooling wants from us: match its version pins, directory layout, env-var conventions, and config defaults rather than fighting them
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-06T17:37:24.032Z
Learning: Pre-commit hooks run `nixfmt`, `nil`, `cargo fmt`, `prettier`, and `taplo`; use `nix flake check` to invoke them outside a commit
🔇 Additional comments (12)
AGENTS.md (1)
21-56: LGTM!docs/anchor.md (7)
1-7: LGTM!
9-20: LGTM!
21-30: LGTM!
32-44: LGTM!
76-95: LGTM!
97-120: LGTM!
122-134: LGTM!programs/fund/SPEC.md (4)
1-11: LGTM!
13-28: LGTM!
40-49: LGTM!
109-123: LGTM!
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
AGENTS.md (1)
41-43: 🧹 Nitpick | 🔵 Trivial | 💤 Low valueConsider adding a forward reference to the test architecture section.
The workflow mentions "litesvm integration test" without prior introduction. While the detailed explanation exists in the "Test architecture" section (lines 108-118), agents encountering step 3 for the first time might benefit from a brief forward reference, e.g., "(see Test architecture section below)".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@AGENTS.md` around lines 41 - 43, Step 3's instruction "Write a failing test." refers to a "litesvm integration test" without prior introduction; update the step text that mentions "programs/fund/tests/*.rs litesvm integration test" to include a short forward reference like "(see Test architecture section below)" or similar, so readers are pointed to the "Test architecture" section for details on the litesvm integration testing approach.
♻️ Duplicate comments (1)
AGENTS.md (1)
237-237: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick winThe
@docs/path notation remains unexplained.This issue was previously flagged. The
@docs/anchor.mdand@docs/sealevel-attacks.mdreferences use a non-standard@prefix that is not documented anywhere in this file. Since the target audience is AI agents who may interpret this as special syntax, and since these won't render as working links in markdown viewers, consider either:
- Using standard relative paths (
docs/anchor.md,docs/sealevel-attacks.md), or- Adding a brief note explaining the
@prefix conventionAlso applies to: 245-245
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@AGENTS.md` at line 237, The references use an unexplained non-standard "`@docs/`..." prefix (e.g., "`@docs/anchor.md`" and "`@docs/sealevel-attacks.md`") which may confuse readers and tools; update AGENTS.md to either (a) replace those occurrences with standard relative paths "docs/anchor.md" and "docs/sealevel-attacks.md" everywhere they appear, or (b) add a single-line note near the top explaining the "`@docs/`" prefix convention and how it maps to the repo path, and then keep the references — ensure you update both the "`@docs/anchor.md`" and "`@docs/sealevel-attacks.md`" instances.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@AGENTS.md`:
- Around line 41-43: Step 3's instruction "Write a failing test." refers to a
"litesvm integration test" without prior introduction; update the step text that
mentions "programs/fund/tests/*.rs litesvm integration test" to include a short
forward reference like "(see Test architecture section below)" or similar, so
readers are pointed to the "Test architecture" section for details on the
litesvm integration testing approach.
---
Duplicate comments:
In `@AGENTS.md`:
- Line 237: The references use an unexplained non-standard "`@docs/`..." prefix
(e.g., "`@docs/anchor.md`" and "`@docs/sealevel-attacks.md`") which may confuse
readers and tools; update AGENTS.md to either (a) replace those occurrences with
standard relative paths "docs/anchor.md" and "docs/sealevel-attacks.md"
everywhere they appear, or (b) add a single-line note near the top explaining
the "`@docs/`" prefix convention and how it maps to the repo path, and then keep
the references — ensure you update both the "`@docs/anchor.md`" and
"`@docs/sealevel-attacks.md`" instances.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 143b7533-91ef-4596-b1c3-6a88a2dfe828
📒 Files selected for processing (1)
AGENTS.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (2)
*
⚙️ CodeRabbit configuration file
Focus on providing constructive criticism. Whenever you see a suboptimal approach, suggest more idiomatic or robust alternative(s). Flag potential footguns. Suggest FP alternatives to mutable/imperative code. Point out architectural flaws like leaky abstractions, tight coupling, wrong level of abstraction, poor type modeling, over-abstraction, unclear domain boundaries. Code should generally be organized based on business concerns rather than technical aspects - suggest improvements if you find violations. Point out gaps in test coverage but suggest tests that are not too coupled to the implementation and actually test domain invariants and business logic.
Files:
AGENTS.md
**/*.md
⚙️ CodeRabbit configuration file
Focus on the contents of the docs and not on cosmetic things like markdown formatting. We use markdown files for various docs including but not limited to the north star system specification, SPEC.md, the plan for how to get there, ROADMAP.md, guidelines for AI contributors, AGENTS.md, project overview and instructions for human contributors, README.md. Think about the target audience of a document when deciding what comment to leave. For specifications and designs, suggest potential product, architectural, and UI/UX improvements. For plans, suggest changes that would make things more parallelizable and deliverable-focused. For instructions, suggest better rules and guidelines and point out missing instructions. In all cases, flag needless bloat, prefer clear concise writing, and consider the structure of the document and order of the sections
Files:
AGENTS.md
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-07T00:27:03.983Z
Learning: `anchor build` must run before `cargo test` because integration tests depend on the compiled `target/deploy/fund.so` artifact to be present at compile time.
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-07T00:27:03.983Z
Learning: Documentation in this repo must be tracked in markdown files (CLAUDE.md, `programs/fund/README.md`, `programs/fund/SPEC.md`, ADRs under `adrs/`, or dedicated docs). Agent memory, scratchpads, or `.tmp/` files do not count as documentation.
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-07T00:27:03.983Z
Learning: Program ID `5nNVyzESLk4QNQh7HgxAAwFmHnN37WUz1aCttBLwFo2e` must be declared in both `programs/fund/src/lib.rs` via `declare_id!` and in `Anchor.toml`'s `[programs.localnet]` — keep them in sync.
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-07T00:27:03.983Z
Learning: Pre-commit hooks via `git-hooks.nix` run `nixfmt`, `nil`, `cargo fmt`, `prettier`, and `taplo`. Run `nix flake check` to invoke them outside a commit.
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-07T00:27:03.983Z
Learning: The `fund` program is an Anchor program. Before touching `programs/fund/src/`, read docs/anchor.md for coverage of core macros (`declare_id!`, `#[program]`, `#[derive(Accounts)]`, `#[account]`), account validation, the 8-byte discriminator, and the IDL/client codegen flow. Note that Anchor does not care about `.rs` file names inside `instructions/` — they are a project convention, not a framework rule.
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-07T00:27:03.983Z
Learning: Use `bun` as the package manager for TypeScript/JavaScript in the app/migrations (declared as `package_manager = "bun"` in Anchor.toml), not yarn or npm.
Learnt from: CR
Repo: data-cartel/fund
Timestamp: 2026-06-07T00:27:03.983Z
Learning: Always succumb to whatever Solana tooling wants. Match its version pins, directory layout, env-var conventions, and config defaults rather than fighting them.
0xgleb
force-pushed
the
docs/create-fund-spec
branch
2 times, most recently
from
a961345 to
abd1943
Compare
Pull request was converted to draft
0xgleb
force-pushed
the
docs/create-fund-spec
branch
2 times, most recently
from
f726122 to
fe15fb5
Compare
0xgleb
force-pushed
the
docs/create-fund-spec
branch
from
fe15fb5 to
aecd009
Compare
0xgleb
force-pushed
the
docs/create-fund-spec
branch
from
aecd009 to
7819e2e
Compare
2 participants
Motivation
The fund program had no written contract for its first instruction and no
shared Anchor reference, so the on-chain work could not be reviewed against an
agreed design. This is split out of the oversized create-fund PR (#3) so the
spec and reference docs can be reviewed on their own.
Solution
programs/fund/SPEC.md— thecreate_funddesign: a singleCreateFundParamsinput (name: [u8; 32]with canonical zero-padding and adocumented collision rationale), accounts, effects (including the stored
name and all three PDA bumps with the re-signing pattern), an explicit
error-conditions section (with the 100% fee-cap rationale), and design
rationale for recording immutable parameters at creation.
quote_mintis anaccount input only — never a params field — and the freeze-authority risk of
the chosen quote mint (e.g. USDC) is documented as accepted by design.
The spec also carries the
depositcontract (share math with its zero-shareand empty-vault guards, capacity semantics and the ADR-0001-gated migration
to
total_assets, accounts, error conditions, sequence diagram) ahead ofthe implementation PR (feat: add the deposit instruction #8), per the contract-before-implementation
workflow.
docs/anchor.md— distilled Anchor essentials (the four macros, accountvalidation — with
UncheckedAccountexplicitly called out as unvalidated —and IDL generation) so reviewers share one mental model.
AGENTS.md— the repo's agent/contributor rules, including thecontract-PR-before-implementation workflow with a carve-out for
preliminary docs-only PRs.
Closes #16