docs: ADR for donation-resistant share pricing

[0xgleb]

🦋 GitButler workspace — open PRs in data-cartel/fund

• docs: spec create_fund and Anchor essentials #6
• feat: add the create_fund instruction #7
• feat: add the deposit instruction #8 (stacked on feat: add the create_fund instruction #7)
• docs: ADR for donation-resistant share pricing #10 ← you are here
• docs: evidence-based security design for the fund #11
• feat: expose the program idl as a flake output #22
• docs: ADR for permissionless NAV attestation #23
• docs: link security-design.md and adrs/ from the README, correct NAV wording #26

---

Motivation

Auditing the deposit instruction surfaced a critical issue (#9): the share
price is read from vault.amount, which anyone can inflate by transferring
quote tokens directly into the vault — the ERC4626 first-depositor inflation
attack. The fix is a design decision (it couples with the eventual NAV /
off-vault AUM model), so it needs a recorded decision before any
implementation.

Solution

Add ADR 0001 laying out the options (virtual-offset, internal total_assets
accounting, dead-shares) with corrected attack-cost math, tradeoffs, and a
recommendation: internal accounting plus a virtual offset, which also seeds
the NAV model the fund needs anyway. The formula contract defines
total_shares as shares_mint.supply (no redundant counter), mandates
zero-output guards on both mint and burn, pins the donation-exclusion
invariant to the ADR 0002 tier model, requires the deposit capacity check to
migrate to total_assets, and constrains the decimals offset against the u64
supply ceiling.

The Release gate decides the sequencing: vault-only total_assets ships now;
off-vault inclusion is hard-gated on ADR 0002's redeemable-NAV model
(redeemable_nav = verifiable_nav + floor(read_nav); Tier-3 attested_nav
never prices mints or burns). Only ADR 0002's owner-ratification items remain
open.

Refs #9
Closes #19

Summary by CodeRabbit

• Documentation
  • Added architectural decision record documenting enhancements to share pricing mechanisms and protective safeguards for vault operations.

[coderabbitai]

Warning

Review limit reached

@0xgleb, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 14 minutes and 29 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 68c170ed-43f4-4afa-bdb6-a7a551c699d3

📥 Commits

Reviewing files that changed from the base of the PR and between 0d1cf75 and 651679f.

📒 Files selected for processing (1)

• adrs/0001-donation-resistant-share-pricing.md

Walkthrough

This PR adds ADR 0001, documenting the decision to implement donation-resistant share pricing for the Fund. The ADR describes the ERC-4626 first-depositor inflation attack, evaluates three alternatives, recommends internal Fund.total_assets accounting with a virtual offset to replace vault.amount-based pricing, specifies executable pricing invariants and formulas, and defines release gates constraining off-vault deployment until NAV-attestation accounting (ADR 0002) is complete.

Changes

Share Pricing Design Decision

Layer / File(s)	Summary
Problem and design options adrs/0001-donation-resistant-share-pricing.md	Frames the ERC-4626 first-depositor donation attack enabled by vault.amount-based share pricing; enumerates three alternatives: virtual offset only (insufficient), internal asset accounting (recommended), and dead-shares/minimum-deposit approaches.
Recommended solution and consequences adrs/0001-donation-resistant-share-pricing.md	Selects internal Fund.total_assets with virtual offset as the solution; specifies consequences including state addition, deposit/withdraw/capacity-check updates, and mandatory inflation reproduction tests.
Pricing invariants and executable formulas adrs/0001-donation-resistant-share-pricing.md	Formalizes the pricing specification: derives share price only from total_assets, enforces zero-output guards, defines virtual offset constants, specifies integer-arithmetic mint/burn formulas using pre-update snapshots, and requires mandatory failure conditions.
Release gates and sequencing adrs/0001-donation-resistant-share-pricing.md	States that total_assets pricing is complete in vault-only mode; hard-gates off-vault deployment on ADR 0002 redeemable NAV accounting; delegates the final sequencing decision to ADR 0002 owner ratification.

Possibly related PRs

• data-cartel/fund#2: Both PRs focus on deposit share-pricing/minting math (first-deposit/pro-rata behavior and related accounting assumptions), so ADR 0001's "donation-resistant" pricing invariants would directly affect the deposit share-minting spec described in programs/fund/SPEC.md.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding an ADR document for donation-resistant share pricing, which is the primary and only alteration in this documentation-only PR.
Linked Issues check	✅ Passed	The PR fully satisfies issue #19's requirement: it establishes ADR 0001 as a recorded architectural decision that weighs options, documents tradeoffs, recommends internal accounting with virtual offset, and defines implementation constraints and release sequencing gates.
Out of Scope Changes check	✅ Passed	All changes are in-scope: the single file addition (ADR 0001) directly addresses the linked issue #19's requirement for a recorded design decision on donation-resistant share pricing with no extraneous modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/share-pricing-adr

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@adrs/0001-donation-resistant-share-pricing.md`:
- Around line 80-83: Update the ADR to replace the optional phrasing about
rollouts with an explicit safety gate: state that if off-vault positions are
enabled then deposits and withdrawals must require an attested NAV (do not allow
vault-only total_assets) and otherwise off-vault deployment must remain behind a
feature flag; reference the terms total_assets (v0, vault-only), attested NAV,
deposits/withdraws, and off-vault positions in the same paragraph and add a
clear release condition sentence (e.g., “Release rule: off-vault = attested NAV
required; until attestation is implemented, off-vault must be feature-flag
disabled”) so the ADR enforces the hard gate rather than leaving it optional.
- Around line 61-74: Add a short "Pricing invariants and formulas" subsection
that states: (1) the share price MUST be computed solely from Fund.total_assets
and total_shares (or equivalent) and MUST NOT read vault.amount; (2) direct
transfers to the vault MUST NOT affect mint/mint_quote or burn/burn_quote
calculations; then provide the explicit mint/burn formulas (e.g., shares_to_mint
= floor(deposit_amount * total_shares / total_assets) or inverse for burns) and
specify initialization and rounding rules for the virtual offset constants
(initial virtual_offset_A, how it is added to total_assets for first-depositor
pricing, and the rounding direction for both minting and burning). Reference the
Fund struct, total_assets field, deposit and withdraw methods, vault.amount, and
the NAV-attestation reconciliation as the authoritative source for off-vault
values.

🪄 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: 0abeb716-9ee8-40cf-aae1-f3164d5af165

📥 Commits

Reviewing files that changed from the base of the PR and between 8678a5d and 802ad88.

📒 Files selected for processing (1)

• adrs/0001-donation-resistant-share-pricing.md

📜 Review details

🧰 Additional context used

📓 Path-based instructions (1)

**/*.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:

• adrs/0001-donation-resistant-share-pricing.md