Firstance — pump.fun Automated Vault + Rule Engine

An on-chain Solana (Anchor) program that automatically sells a token allocation according to transparent, marketcap- and time-triggered rules, and burns the remainder. Sale proceeds always go to a fixed, immutable address chosen at setup.

The rules are enforced on-chain — no one, not even the authority, can change them, redirect the funds, or sell to themselves.

⚠️ This is a technical tool, not financial or legal advice.

How it works

The design is hybrid:

• On-chain program (programs/pumpfun-vault/) — enforces every rule. This is the trust anchor.
• Off-chain keeper (keeper/) — a permissionless bot that only triggers actions at the right time. It cannot change anything; the program re-checks every rule on-chain.

The rules

Daily sell rates below are shown as a share of total supply (with 50% of the supply vaulted). On-chain the fixed base is the vaulted allocation itself, at 2× these rates — e.g. 0.25% of supply = 0.5% of the allocation — so they map directly to the verified program (rules.rs: 50 / 20 / 10 bps of initial_allocation, not the remaining balance).

Marketcap	Action	Daily sell
First 24h, < $100k	Liquidate the whole vault → LiquidatedAll	100% of vault
$100k – $1M	Daily sell	0.25% of supply
$1M – $10M	Daily sell	0.1% of supply
$10M – $100M	Daily sell	0.05% of supply
≥ $100M (Terminal)	Burn the ENTIRE remainder (no selling) → Burned	100% of vault

• No tier hysteresis — always the current marketcap band; if the price drops, it returns to a lower tier.
• Terminal is permanent — once ≥ $100M the phase never reverts; finalize_burn burns the ENTIRE remaining vault (no terminal selling) → Burned.
• Daily sells are split into 5 intra-day slices (mini-TWAP) to reduce price impact.
• Adaptive slippage — starts tight, widens gradually if a sell reverts, capped at 4% by the program.

Trust model

The published interface (see the on-chain IDL) makes the guarantees verifiable:

• The authority can only initialize, set_paused (emergency stop), and decommission (and only when the vault is empty). It cannot change the rules, redirect funds, or sell to itself.
• Sells, burns, and withdrawals are permissionless (anyone can trigger them), but proceeds always go to the fixed proceeds_recipient, or are burned.
• Marketcap is read from the pump.fun bonding curve / PumpSwap pool + a Pyth SOL/USD price, validated for Full-verification, feed-id, and staleness.
• Supports Token-2022 coins (and legacy SPL Token).

On-chain

• Program ID (mainnet): FirstJpXgzGf2oBDsEa2eAqez2fKJdAUJi6R7gP7PXbj
• Upgradeable (BPFLoaderUpgradeable) so a sell-path issue can be fixed; the failure mode is "revert & retry", never fund loss.
• On-chain IDL — the full interface (instructions, accounts, state, errors) is published on-chain, so every keeper action is decoded and human-readable on Solana explorers.
• security.txt — the binary carries a neodyme security.txt (visible in the Solana Explorer "Security" tab).

Repository layout

programs/pumpfun-vault/    # the Anchor program (the contract)
  src/
    lib.rs                 # program entry (9 instructions)
    state.rs               # VaultState + Phase
    rules.rs               # pure tier logic + unit tests
    oracle.rs              # marketcap read + sell CPIs (curve / PumpSwap) + Pyth parse
    errors.rs              # error codes
    instructions/          # initialize / evaluate / finalize / admin
keeper/                    # off-chain trigger bot (TypeScript)
tests/                     # litesvm integration tests (no validator needed)
test-programs/mock-pump/   # no-op program that stands in for pump in the tests
target/idl/                # published IDL
vendor/ark-ff-macros/      # pinned/patched build dependency
build.sh                   # build wrapper (pinned toolchain)

Build & test

./build.sh                              # anchor build (--no-idl) + mock program
cargo test -p pumpfun-vault             # 16 unit tests (rules + oracle)
npm install && npm run test:litesvm     # 19 integration tests, no local validator

Keeper

The keeper runs periodically (cron) and needs its own low-privilege key (it only pays tx fees — it can never move funds). Configure it via keeper/.env (copy keeper/.env.example). See keeper/README.md.

Security

Please report vulnerabilities privately — see SECURITY.md.

License

TBD — add a LICENSE file before relying on this in production (MIT or Apache-2.0 are standard for Solana programs).