Tradeable token grants on Solana. The vesting position itself is a transferable NFT — selling it sells the future stream.
┌──────────────┐ ┌──────────────┐
│ Creator │ │ Holder #N │
│ (escrows) │ │ (claims) │
└──────┬───────┘ └──────▲───────┘
│ SPL transfer │ withdraw
▼ │ (signer = receipt holder)
┌──────────────────────────┐ ┌──────────────────────┐
│ Vault (PDA-owned) │ ──────► │ Receipt NFT (1/1) │
│ authority = schedule │ │ transferable │
└──────────────────────────┘ └──────────┬───────────┘
▲ │
│ PDA-signed CPI │ SPL transfer
│ ▼
┌──────────────────┐ ┌──────────────┐
│ VestingSchedule │ │ Holder #N+1 │
│ (state PDA) │ │ (next owner)│
└──────────────────┘ └──────────────┘
LiquidVest is a Solana program (Anchor 0.30) that escrows SPL tokens behind a transferable Receipt NFT. Whoever holds the NFT can claim whatever has vested. Transferring the NFT transfers the future stream. Cancellable schedules pay vested-unwithdrawn to the current holder and return the unvested remainder to the creator.
This solves the illiquidity built into every existing Solana vesting protocol —
see docs/PITCH.md for the product framing and
docs/COMPETITIVE.md for the comparison vs. Streamflow,
Bonfida, Hedgey, and Sablier.
.
├── programs/vesting/ Anchor program (Linear, Cliff, Step curves; receipt NFT; cancellation)
│ ├── src/ instruction handlers + state + curve math
│ └── tests/properties.rs proptest invariants over the vesting math
├── tests/vesting.ts Bankrun integration suite (12 tests, including the tradeable-receipt path)
├── cli/src/index.ts CLI: airdrop, create-mint, create-schedule, info, withdraw, transfer-receipt, cancel, list-positions
├── indexer/ Node + better-sqlite3 + Express; consumes Anchor logs
├── app/ Next.js 14 + wallet-adapter + Tailwind + recharts
└── docs/
├── PITCH.md one-pager for the product
├── COMPETITIVE.md feature matrix vs. Streamflow / Bonfida / Hedgey / Sablier
├── ROADMAP.md v1 / v2 / v3 / v4
├── USER_RESEARCH.md 4 personas, jobs to be done
└── DEMO_SCRIPT.md 90-second narrated demo for a Loom
| Tool | Version | Notes |
|---|---|---|
| Solana CLI | ≥ 1.18 (Agave 3.x works) | sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)" |
| Anchor | exactly 0.30.1 | cargo install --git https://github.com/coral-xyz/anchor avm --force && avm install 0.30.1 && avm use 0.30.1 |
| Rust | stable (any from 1.85+) | The vendored anchor-syn patch (see "Vendored fixes" below) makes the IDL build work on modern Rust. |
| Node | ≥ 20 | yarn or pnpm both work; examples below use yarn since Anchor.toml defaults to it. |
| Default Solana keypair | ~/.config/solana/id.json |
If missing, run solana-keygen new --no-bip39-passphrase once. Anchor's wallet provider needs this even for bankrun runs. |
git clone <this-repo> liquidvest && cd liquidvest
# 1. Install JS deps (root + indexer + app)
yarn install # root: program tests + CLI
yarn --cwd indexer install # indexer
yarn --cwd app install # frontend
# 2. Build the program (produces target/deploy/vesting.so + IDL + types)
anchor build
# 3. Test
yarn test # bankrun: 13 specs, ~1s
yarn test:rust # proptest: 4 invariants over the curve math
yarn test:all # bothThe frontend is a Next.js app that talks to the on-chain program directly
through the user's wallet, and reads indexed positions from a small local
service. Three components: a Solana cluster (devnet works out of the
box; localnet via solana-test-validator if you want to mint test tokens),
the indexer (a Node + SQLite REST API), and the Next.js dev server.
# Prerequisites already done: yarn install (×3) + anchor build
# (the indexer and the frontend both load target/idl/vesting.json at startup)
# Terminal 1 — indexer (REST API on :3001)
yarn --cwd indexer dev
# Terminal 2 — Next.js dev server (UI on :3000)
yarn --cwd app devThen open http://localhost:3000 and:
- Install a Solana wallet extension if you don't have one — Phantom or Solflare.
- Click Connect wallet in the header.
- Switch the cluster pill in the header to
Devnet(default) orLocalnet(if you also started asolana-test-validator). - Click Create to walk through the schedule wizard, then My positions for the dashboard.
# Terminal 3 — local validator
solana-test-validator
# Then in a regular shell, set up the test environment
solana airdrop 5
yarn cli create-mint --decimals 6 --supply 1000000 --cluster localnet
# → copy the mint address; paste it into the create wizardBy default the indexer listens to http://127.0.0.1:8899. To watch devnet:
LIQUIDVEST_CLUSTER=devnet yarn --cwd indexer dev- "Indexer offline" banner on
/positions— start the indexer:yarn --cwd indexer dev. The landing page and/createwizard work without it; only the dashboard depends on it. ws error: connect ECONNREFUSED 127.0.0.1:8900in the indexer log — harmless. It means there's no Solana validator on the configured cluster to subscribe to; the REST API still serves cached data.Module not found: 'pino-pretty'in Next.js output — harmless. An optional logger dep pulled in by@walletconnect. Doesn't affect the running app.- Dashboard shows "No positions" — expected on a fresh setup. Create
a schedule via
/create(oryarn cli create-schedule …) and the indexer will pick it up via Anchor logs.
Two non-obvious things in this repo exist for reproducibility, not by choice:
vendor/anchor-syn/— Anchor 0.30.1's IDL builder callsproc_macro2::Span::source_file(), which newer Rust toolchains removed. The crates.io copy therefore won't compile on Rust ≥ 1.94. We vendor the one-line patch (the gated block is for type-alias inference, which the program doesn't use) and point[patch.crates-io]in the rootCargo.tomlat it. No manual setup needed —anchor buildpicks it up automatically..cargo/config.tomlis intentionally absent. We tried propagating--cfg procmacro2_semver_exemptvia build flags; it doesn't survive cross-compile boundaries. Vendoring the patched crate is the only stable fix.
If you upgrade to Anchor 0.31+ later, you can delete vendor/anchor-syn/ and
the [patch.crates-io] block — the upstream issue is fixed there.
error: not a directory: …/platform-tools/rust/lib— Solana'scargo-build-sbfcached a truncatedplatform-toolsarchive. Delete theplatform-tools/directory under~/.local/share/solana/install/releases/<rev>/solana-release/bin/platform-tools-sdk/sbf/dependencies/and re-runanchor build; it will re-download a fresh copy.Unable to read keypair file ~/.config/solana/id.json— runsolana-keygen new --no-bip39-passphrase --forceonce.anchor testcomplains about a local validator — bankrun is fully in-process; we don't need a real validator. Theyarn testscript in this repo wrapsanchor test --skip-local-validator --skip-deployfor exactly this reason. If you want to invokeanchor testdirectly, pass those flags yourself.
pub struct VestingSchedule {
pub creator: Pubkey,
pub initial_recipient: Pubkey, // for display + non-transferable guard
pub mint: Pubkey, // underlying SPL asset
pub receipt_mint: Pubkey, // the position NFT (decimals=0, supply=1)
pub seed: u64,
pub curve: Curve, // Linear { start, cliff, end } | Cliff { start, cliff } | Step { start, step_secs, num_steps }
pub total_amount: u64,
pub withdrawn_amount: u64,
pub cancellable: bool,
pub cancelled: bool,
pub transferable: bool,
/* bumps */
}| Account | Seeds |
|---|---|
schedule |
["schedule", creator, mint, seed_le_bytes] |
vault |
["vault", schedule] |
receipt_mint |
["receipt", schedule] |
| Instruction | Signer | Effect |
|---|---|---|
create_schedule(seed, params) |
creator | Init schedule + vault + receipt mint; mint 1 NFT to initial_recipient; disable mint authority; escrow total_amount from creator. |
withdraw() |
receipt holder | Transfer vested-but-unclaimed underlying to the holder's ATA. Non-transferable schedules also require signer == initial_recipient. |
cancel() |
creator | Pay vested-unwithdrawn to current receipt holder; return unvested to creator; close vault and schedule. |
Linear: vested(t) =
0 if t < cliff_ts
total if t ≥ end_ts
total · (t − start_ts) / (end−start) otherwise
Cliff: vested(t) = 0 if t < cliff_ts else total
Step: vested(t) =
0 if t < start_ts
total · min(⌊(t − start)/step⌋, n) / n
All variants are computed in u128 with checked_mul / checked_div. The
workspace Cargo.toml enables overflow-checks = true in release builds.
Property tests in programs/vesting/tests/properties.rs fuzz the math against
thousands of randomized inputs and assert: bounded by total, monotonic in
t, and never returns Err on well-formed inputs.
| Threat | Mitigation |
|---|---|
| Creator drains vault after creation | Vault authority is the schedule PDA; only the program can sign outflows. |
| Recipient redirection on cancel | current_holder_token_account.owner == current_holder_receipt_account.owner constraint. |
| Claim by random wallet | holder_receipt_account.amount ≥ 1 constraint + token::authority = holder. |
| Non-transferable bypass via SPL transfer | holder == initial_recipient check at withdraw time, independent of who currently holds the NFT. |
| Integer overflow | u128 intermediate, checked arithmetic, release-profile overflow checks. |
| Schedule substitution | All seeds (creator, mint, seed) baked into PDA derivation; has_one = creator, mint, receipt_mint. |
| Backdated start | start_ts ≥ now − 1 day. |
- No formal audit (planned for v4 — see
ROADMAP.md). - Underlying assets with
transfer_feeextension are not rejected at creation; the math will silently under-distribute. Detect off-chain for now. - Token-2022 underlying is unsupported; receipt is itself classic SPL Token (decimals=0, supply=1, mint authority disabled). Token-2022 receipt with TokenMetadata extension is on the v3 roadmap.
# Set up a test environment
pnpm cli airdrop --sol 2 --cluster devnet
pnpm cli create-mint --decimals 6 --supply 1000000
# Issue a 1-year schedule with a 30-day cliff
pnpm cli create-schedule \
--recipient <PUBKEY> \
--mint <MINT_PUBKEY> \
--amount 100000 \
--curve linear --cliff-days 30 --duration-days 365 \
--cancellable
# The recipient (or whoever holds the receipt) claims
pnpm cli --wallet ~/.config/solana/recipient.json withdraw <SCHEDULE_PDA>
# Sell the position by transferring the receipt
pnpm cli transfer-receipt <RECEIPT_MINT> <NEW_OWNER_PUBKEY>
# Creator cancels (only if cancellable; pass current holder)
pnpm cli cancel <SCHEDULE_PDA> --current-holder <PUBKEY>Setup and run instructions live in Quick start → Run the frontend above.
The Next.js app under app/ covers:
- Landing — pitch, "how it works" diagram, competitive matrix.
/create— wizard with mint inspection, curve preview chart, sign-and-submit./positions— issued-by-you and held-by-you sections, hydrated from the indexer with a wallet-scoped query./position/[mint]— live curve, real-time claimable amount, claim and receipt-transfer actions in one pane.
See docs/DEMO_SCRIPT.md for the 90-second walkthrough.
yarn test # bankrun integration suite — 13 specs, ~1s
yarn test:rust # proptest invariants over the vesting math — 4 tests
yarn test:all # both, sequentially
# Once the indexer is running, the CLI can target it
yarn --cwd indexer dev &
yarn cli list-positionsMIT. See LICENSE — fork it, ship it, swap it for something better.
Built by Eli Benbaruk Feedback welcome — open an issue or DM.
