Skip to content
Mini-DApp

Token vesting vault mini-DApp

  • Intermediate
  • Conway era
  • Draft / WIP
  • v0.1.0
TL;DR

A time-locked vesting contract with a clean web UI. Owner deposits ADA for a beneficiary; beneficiary can claim after the deadline; owner can reclaim anytime. Demonstrates Aiken validator design, inline datums, validity intervals, collateral handling, and reference scripts as a complete end-to-end pattern.

A time-locked vesting contract with a clean web UI. Owner deposits ADA for a beneficiary; beneficiary can claim after the deadline; owner can reclaim anytime. Demonstrates Aiken validator design, inline datums, validity intervals, collateral handling, and reference scripts as a complete end-to-end pattern.

Why this DApp matters

Most “smart contract tutorials” stop after aiken build. This DApp continues from there: how does the validator integrate with off-chain code, how does the frontend present the vest, how do you deploy a reference script to save fees, how do you handle the unlock UX when the user doesn’t know exactly when the deadline lands?

It’s the simplest non-trivial contract that touches every layer:

  • A non-trivial validator (two paths: owner-cancel, beneficiary-claim-after-deadline)
  • Inline datums carrying typed state
  • Validity intervals as a time-checking mechanism
  • Collateral handling
  • Reference scripts as a fee optimisation
  • A frontend with two distinct flows (owner setup vs. beneficiary claim)

What you’ll see when you run it

As an owner:

  1. Connect wallet → click “Create vest”
  2. Form: amount in ADA, beneficiary address, unlock date/time
  3. Sign → ADA locks at the script address
  4. Dashboard shows your active vests with a “Cancel” option (works anytime)

As a beneficiary:

  1. Connect wallet → app queries for vests where you’re the beneficiary
  2. Each vest shows: amount, deadline, status (locked / claimable / claimed)
  3. Once deadline passes → “Claim” button activates
  4. Sign → ADA arrives in your wallet

Architecture

On-chain (Aiken): validators/vesting.ak — about 30 lines. The validator:

pub type VestingDatum {
  lock_until: Int,
  owner: VerificationKeyHash,
  beneficiary: VerificationKeyHash,
}
validator vesting {
  spend(datum_opt, _redeemer, _, tx) {
    expect Some(datum) = datum_opt
    or {
      key_signed(tx.extra_signatories, datum.owner),
      and {
        key_signed(tx.extra_signatories, datum.beneficiary),
        valid_after(tx.validity_range, datum.lock_until),
      },
    }
  }
}

Off-chain (Mesh): Three scripts:

  • lock.ts — builds the locking transaction (sends ADA to script address with inline datum)
  • unlock.ts — builds the unlocking transaction (with validity interval and collateral)
  • deploy-reference.ts — one-time deployment of the reference script

Reference script registry: script-registry.json tracks where the reference script UTxO lives. Used by unlock.ts to avoid inlining the script bytes (saves ~70% on unlock fees).

Frontend: Next.js 14 with two main routes:

  • /owner — vest creation + cancellation dashboard
  • /beneficiary — claim dashboard (queries Blockfrost for UTxOs at the script address)

File layout

dapps/vesting-vault/
├── on-chain/
│   ├── validators/vesting.ak
│   ├── aiken.toml
│   └── plutus.json              (generated by aiken build)
├── off-chain/
│   ├── lock.ts
│   ├── unlock.ts
│   ├── deploy-reference.ts
│   └── script-registry.json
├── frontend/
│   ├── app/
│   │   ├── owner/page.tsx
│   │   ├── beneficiary/page.tsx
│   │   └── api/vests/route.ts   # Lists vests at script addr by beneficiary
│   ├── components/
│   │   ├── VestForm.tsx
│   │   ├── VestCard.tsx
│   │   └── ClaimButton.tsx
│   └── lib/
│       ├── lock.ts              (uses off-chain/lock.ts)
│       └── unlock.ts            (uses off-chain/unlock.ts)
└── README.md

Running it locally

git clone https://github.com/pbwebdev/LearnCardano.git
cd LearnCardano/dapps/vesting-vault
# Build the validator
cd on-chain
aiken build
cd ..
# Deploy the reference script (one-time)
cd off-chain
npm install
node deploy-reference.ts
# Note the txHash + index that gets logged — saved automatically to script-registry.json
# Run the frontend
cd ../frontend
npm install
cp .env.example .env.local  # add Blockfrost key
npm run dev

Wallet must be on preview testnet with some preview ADA.

What this teaches (recipe by recipe)

  • vesting-validator-aiken-mesh — writing the validator and basic lock/unlock flow
  • aiken-unit-tests — testing the validator with aiken check (the repo includes the test suite from this recipe)
  • reference-scripts-aiken-mesh — deploying and using the reference script

Pitfalls baked into the design

The DApp is structured to demonstrate three common pitfalls and their fixes:

  • validity-interval-not-set — the unlock flow always sets a validity interval; without it, the time check fails
  • collateral-not-set — the unlock flow always includes collateral; the wallet is checked at connect time
  • min-ada-with-metadata — the lock flow trusts Mesh’s calculation rather than hard-coding lovelace amounts

Reading the unlock script will show you what “production-grade” looks like for these three issues.

Test transaction examples

Real preview-testnet transactions from this DApp are listed in the post sidebar. Good ones to inspect on Cardanoscan:

  • The “Lock 5 ADA for 48h vest” transaction shows the inline datum structure
  • The “Beneficiary claim after deadline” transaction shows the redeemer + validity interval + collateral
  • The “Reference script deployment” transaction shows where the script bytes live

Production hardening (left as an exercise)

The repo version is a teaching artifact. To productionise:

  • Multi-asset support (currently only ADA; native tokens locked alongside ADA are a small extension)
  • Cliff vesting (one big release at deadline) → linear vesting (continuous release over a window)
  • Multiple beneficiaries per vest (requires datum redesign)
  • Owner withdrawal of “yield” — letting the locked ADA earn delegation rewards while locked (this is a real benefit of Cardano’s stake-while-locked model and worth a follow-up DApp)
  • Audit before mainnet

Demo

No public demo URL yet — run locally for now. Production deployment planned alongside the Cardano Content Creator Consortium video series.

Architecture

Aiken validator at validators/vesting.ak with three rules: spend allowed if owner signs (anytime) OR beneficiary signs and the validity-interval lower bound is past the deadline. The off-chain layer is two scripts — lock.ts builds a transaction sending ADA to the script address with an inline VestingDatum, and unlock.ts builds a transaction spending the script UTxO with a redeemer and a validity interval covering "now." The reference script is deployed once to a separate UTxO and reused, cutting per-transaction fees by ~70%. Frontend is a minimal Next.js page with two flows: owner sets up a vest, beneficiary checks status and claims when ready.

On-chain

Aiken (validator version V3)

Off-chain

Mesh SDK 1.x, BlockfrostProvider, custom script registry helper

Frontend

Next.js 14 with @meshsdk/react

About Learn Crypto

Hi, I'm Peter, I've been podcasting since 2013

After years of trading and learning about crypto, I decided that Cardano was my chain of choice and put all my efforts into understanding everything about Cardano and the broader crypto and blockchain space. Learn Crypto is where I share all that I learn with you.

Follow & contact Peter (opens Chatsoon in a new tab)

Peter Bui
ADAOZ Stake Pool

Support Our Content

Delegate to Our Stake Pool ADAOZ

Delegate to our stake pool and help us continue to create content for the Cardano ecosystem.

Pool ID: 6658713e2cbfa4e347691a0435953f5acbe9f03d330e94caa3a0cfb4

Stake Your ADA

Keep Up To Date!

Sign up for our newsletter. Latest crypto news, airdrops, courses and everything you need to know about Cardano, Midnight and the wider crypto space.