Skip to content

AGENTS.md

Latest commit

 

History

History
220 lines (160 loc) · 8.66 KB

AGENTS.md

File metadata and controls

220 lines (160 loc) · 8.66 KB

AGENTS.md

This repository contains two Solana programs that implement two different market-maker models:

  • AMM (scale_amm): a standard on-chain automated market maker (Uniswap/Raydium-style).
  • VMM (scale_vmm): a “pre-graduation” virtual market maker (pump.fun pre-graduation-style) that maintains pair-level ledger state without provisioning discrete liquidity pools, and graduates pairs to the AMM after a liquidity threshold is met.

This document tells Codex agents how to reason about the codebase, terminology, fee mechanics, and required update workflow.

Canonical vocabulary

Token pair

A pair is the trading relationship between two mints:

  • tokenA_mint and tokenB_mint

Pairs exist in both AMM and VMM. A pair is the conceptual “market.”

Pool (AMM only)

A pool is an on-chain account/state bundle that holds reserves (liquidity) for a given pair inside the AMM program.

  • AMM: pairs are realized as pools that hold real reserves and price is determined by the AMM invariant.
  • VMM: there are no discrete pools; state is maintained at the pair level (ledger-style) and swap math derives from that state.

Rule of thumb:

  • If you see reserves in token vaults / pool accounts → AMM pool.
  • If you see pair-level counters/ledgers with no “pool vaults” semantics → VMM pair state.

High-level model: AMM vs VMM

AMM (Automated Market Maker) — scale_amm

What it is:
A typical on-chain DEX AMM program. Think Uniswap/Raydium.

Key properties:

  • Independent program: it can create and manage pairs/pools on its own.
  • Has pool-specific state & accounts (vaults/reserves).
  • Swaps/liquidity operations are executed against pool reserves.

Pair creation paths:

  • Direct AMM creation: create pairs/pools directly in AMM via AMM create* methods.
  • VMM graduation helper: create_from_vmm() can create an AMM pool from an existing VMM pair state.

VMM (Virtual Market Maker) — scale_vmm

What it is:
A “pre-graduation” market maker where there are no pools. It tracks pair state (ledger maintenance) and computes pricing/execution from that state.

Key properties:

  • Dependent program: pairs are meant to graduate to AMM after threshold conditions.
  • Maintains pair-level state rather than pool reserves.
  • Graduation is a first-class lifecycle step.

Graduation (VMM → AMM)

A VMM pair graduates to an AMM pool when a liquidity threshold is met.

  • The threshold is purely a liquidity number, e.g. tokenA balance, reservesA, or similar numeric metric in VMM state.
  • Graduation results in creating an AMM pool/pair, typically via the AMM helper create_from_vmm() (or equivalent graduation flow).

Agent requirement: when editing graduation logic, confirm:

  • which exact numeric field constitutes the threshold metric,
  • where it is updated,
  • who is allowed to trigger graduation,
  • how state is migrated/initialized in the AMM.

Fees (applies to both AMM and VMM)

There are two fee types on both programs:

1) Platform fees (protocol-owner fees)

  • Distributed to a single beneficiary wallet (the protocol owner beneficiary).
  • The beneficiary can be changed independently for AMM and VMM.
  • Changes are performed via the Authority wallet.

Agent requirement:

  • Treat platform-fee recipient as privileged configuration.
  • Ensure authority checks exist and are tested.
  • Keep AMM/VMM config separation explicit (do not accidentally share config unless intentionally designed).

2) Creator fees (pair/pool creator fees)

  • Distributed to the individual pair/pool creator(s).
  • The creator sets:
    • fee bps,
    • distribution across up to 5 wallets.

Agent requirement:

  • Validate constraints (bps bounds, max wallet count = 5).
  • Validate distribution totals (if applicable) and recipient uniqueness rules (if defined).
  • Ensure fee calculations are deterministic and safe from rounding exploits.

What to check when modifying swap / liquidity / fee code

When changing any behavior in either program:

  1. Model correctness

    • AMM changes must respect pool/reserve invariants and vault accounting.
    • VMM changes must respect ledger-style state transitions and graduation conditions.

  2. Fee correctness

    • Confirm both platform and creator fees are applied exactly once.
    • Confirm fee bps interpretation and rounding behavior.
    • Confirm fee recipients are correct for the program (AMM vs VMM).

  3. Security & safety

    • Check signer/authority constraints.
    • Check overflow/underflow, rounding, and edge-cases (0 liquidity, tiny swaps, max bps).
    • Add explicit negative tests for unauthorized calls and invalid configs.
    • Consider common Solana program risks (account spoofing, incorrect PDA derivations, missing ownership checks).

Repository structure (expected)

  • README.md (root): protocol-wide overview, repo usage, contributing, testing, SDK, scripts pointers.
  • scale_amm/README.md: AMM-specific instructions, methods, accounts, invariants, fee behavior.
  • scale_vmm/README.md: VMM-specific instructions, methods, state model, graduation, fee behavior.
  • test/README.md: how tests are executed, checklist, and execution report conventions.
  • ../sdk/README.md: TypeScript SDK usage, dependencies, exported methods, minimal snippets for every function.
  • ../utils/scripts/README.md: deployment/config scripts usage + required environment variables.
  • AGENTS.md (this file): agent-specific guidance; keep it up to date.

Mandatory workflow for any update (non-negotiable)

Whenever implementing a new feature, changing behavior, or removing functionality:

A) Update docs (README family)

Update all relevant guides where applicable:

  1. Root README.md

    • protocol-wide guides
    • repo layout / “what’s where”
    • contribution + testing + SDK + scripts overview

  2. Program README(s)

    • scale_amm/README.md: program methods, behaviors, features, fee rules, invariants
    • scale_vmm/README.md: program methods, pair ledger model, graduation threshold, fee rules

  3. test/README.md

    • how tests are run
    • latest checklist
    • execution report (keep current)

  4. ../sdk/README.md

    • TS SDK dependencies
    • exposed methods list
    • minimal usage snippet for every function

  5. ../utils/scripts/README.md

    • deployment/config scripts
    • required env vars
    • operational steps and caveats

B) Review AGENTS.md

  • Before finalizing changes, re-read AGENTS.md and update any outdated agent guidance to match the new reality.

C) Tests and coverage

  • Read through the entire test suite relevant to the change.
  • Add/update tests for:
    • positive flows,
    • negative cases (unauthorized, invalid inputs),
    • edge cases (0/1 amounts, max bps, rounding),
    • potential attack paths.
  • Run tests repeatedly until all tests pass.
  • Aim for maximum practical coverage around new/modified logic.

D) Scripts and tooling

  • Update deployment/config/helper scripts to accommodate new state, new instructions, migrations, or new methods.

Implementation notes agents should preserve

  • AMM independence: AMM must remain usable without VMM.
  • VMM dependence: VMM pairs are expected to graduate to AMM and should not accidentally become “AMM-like pools.”
  • Graduation threshold: must remain a numeric liquidity metric; do not introduce implicit thresholds without documenting and testing them.
  • Fee separation: platform fee configuration must remain separable between AMM and VMM.

Agent behavior guidelines (how to operate in this repo)

  • Prefer explicit naming in code/docs:
    • Use “pair” for the conceptual market.
    • Use “pool” only for AMM on-chain reserve state.
  • When touching fee logic, update both:
    • on-chain program logic
    • SDK helper functions + docs
    • tests (including negative and rounding tests)
  • If you change any instruction layouts / account schemas:
    • update program README(s)
    • update SDK typing and usage snippets
    • update scripts and env var docs
    • add migration notes if needed

Questions to ask before starting a large change

If a prompt is ambiguous, resolve these before implementing:

  1. Which program is being modified: AMM, VMM, or both?
  2. For VMM changes: does it affect graduation threshold or migration?
  3. Which numeric field defines “liquidity threshold” for graduation?
  4. Any changes to:
    • platform fee beneficiary authority,
    • creator fee wallet list constraints,
    • fee bps bounds,
    • rounding rules?

If the prompt does not specify these and the change depends on them, ask targeted questions rather than guessing.