feat: add the deposit instruction

[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 ← you are here (stacked on feat: add the create_fund instruction #7)
• docs: ADR for donation-resistant share pricing #10
• 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

With create_fund in place, the fund needs deposits: an investor swaps quote
tokens for freshly-minted shares. This is the first instruction that moves
value into the vault, so the share-price math and the safety checks have to be
right.

Solution

Add the deposit instruction (stacked on create_fund):

• Transfers amount quote tokens from the investor's ATA into the vault, then
  mints shares to the investor (the fund PDA signs the mint).
• Share math: the first deposit (supply == 0) anchors price at 1:1 — a
  pre-seeded donation accrues harmlessly to the first depositor; outstanding
  shares against an empty vault are rejected (EmptyVaultWithShares) so no
  one can buy in at a fake 1:1 price and dilute holders; otherwise shares are
  pro-rata to the pre-deposit AUM, rounded down, with zero-share dust deposits
  rejected.
• Capacity is enforced with checked_add (overflow-safe); the proportional
  math uses u128 intermediates with a checked back-cast to u64. The
  capacity/price reads of vault.amount migrate to internal total_assets
  per ADR 0001 (documented in the SPEC deposit section, which lands with the
  spec PR docs: spec create_fund and Anchor essentials #6).
• The vault and shares mint carry explicit token::mint/token::authority/
  mint::authority constraints; the investor's shares ATA is
  init_if_needed, with the exists-path pinning verified by a negative test.
• litesvm integration tests at programs/fund/tests/test_deposit.rs: happy
  path, pro-rata second deposit through the existing ATA, and rejection paths
  (zero amount, over-capacity, drained-vault invariant break, zero-share
  dust, substituted non-canonical shares account) — each pinned to its exact
  error code.

The pure shares_for_deposit math is unit-tested (first deposit, donated
vault, pro-rata, round-down, zero-share and empty-vault rejections,
overflow). Folds in the deposit feedback from the spec review (#2).

Closes #18

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: e318999f-aaa9-4055-af5d-0591197a946e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/deposit-instruction

---

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.}