Skip to content

About

Tradeable token grants on Solana — the vesting position is a transferable NFT, so selling the receipt sells the future stream. Anchor 0.30 program + Next.js frontend + Node/SQLite indexer.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

LiquidVest

Tradeable token grants on Solana. The vesting position itself is a transferable NFT — selling it sells the future stream.

Anchor License Solana

LiquidVest landing page

On-chain architecture

              ┌──────────────┐                  ┌──────────────┐
              │   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)│
              └──────────────────┘               └──────────────┘

TL;DR

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.

What's in here

.
├── 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

Quick start (5 minutes, all local)

Prerequisites

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.

Build & test the program

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        # both

Run the frontend (with dashboard)

The 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 dev

Then open http://localhost:3000 and:

  1. Install a Solana wallet extension if you don't have one — Phantom or Solflare.
  2. Click Connect wallet in the header.
  3. Switch the cluster pill in the header to Devnet (default) or Localnet (if you also started a solana-test-validator).
  4. Click Create to walk through the schedule wizard, then My positions for the dashboard.

Optional: localnet with funded test tokens

# 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 wizard

Targeting devnet from the indexer

By default the indexer listens to http://127.0.0.1:8899. To watch devnet:

LIQUIDVEST_CLUSTER=devnet yarn --cwd indexer dev

Frontend troubleshooting

  • "Indexer offline" banner on /positions — start the indexer: yarn --cwd indexer dev. The landing page and /create wizard work without it; only the dashboard depends on it.
  • ws error: connect ECONNREFUSED 127.0.0.1:8900 in 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 (or yarn cli create-schedule …) and the indexer will pick it up via Anchor logs.

Vendored fixes

Two non-obvious things in this repo exist for reproducibility, not by choice:

  • vendor/anchor-syn/ — Anchor 0.30.1's IDL builder calls proc_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 root Cargo.toml at it. No manual setup needed — anchor build picks it up automatically.
  • .cargo/config.toml is intentionally absent. We tried propagating --cfg procmacro2_semver_exempt via 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.

Common first-run hiccups

  • error: not a directory: …/platform-tools/rust/lib — Solana's cargo-build-sbf cached a truncated platform-tools archive. Delete the platform-tools/ directory under ~/.local/share/solana/install/releases/<rev>/solana-release/bin/platform-tools-sdk/sbf/dependencies/ and re-run anchor build; it will re-download a fresh copy.
  • Unable to read keypair file ~/.config/solana/id.json — run solana-keygen new --no-bip39-passphrase --force once.
  • anchor test complains about a local validator — bankrun is fully in-process; we don't need a real validator. The yarn test script in this repo wraps anchor test --skip-local-validator --skip-deploy for exactly this reason. If you want to invoke anchor test directly, pass those flags yourself.

Program design

State

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 */
}

PDAs

Account Seeds
schedule ["schedule", creator, mint, seed_le_bytes]
vault ["vault", schedule]
receipt_mint ["receipt", schedule]

Instructions

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.

Vesting math

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.

Security

What's built in

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.

Out of scope (v1)

  • No formal audit (planned for v4 — see ROADMAP.md).
  • Underlying assets with transfer_fee extension 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.

CLI

# 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>

Frontend

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.

Testing

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-positions

License

MIT. See LICENSE — fork it, ship it, swap it for something better.

Contact

Built by Eli Benbaruk Feedback welcome — open an issue or DM.

About

Tradeable token grants on Solana — the vesting position is a transferable NFT, so selling the receipt sells the future stream. Anchor 0.30 program + Next.js frontend + Node/SQLite indexer.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages