Klever Vesting

Token sale with configurable vesting on KleverChain.

A complete platform for launching token sales where purchased tokens are locked in a smart contract and released over time according to configurable vesting schedules. Features early-exit penalties, extension bonuses, whitelisted sale phases, and a hardened security model.

Built on KleverChain with Rust smart contracts, a SolidJS frontend, and a Rust/Axum backend API.

Architecture

Component	Technology	Directory
Smart Contract	Rust / klever_sc 0.45.0 (KVM WASM)	contracts/
Frontend	SolidJS + Vite + TypeScript	www/
Backend API	Rust / Axum + PostgreSQL + Redis	api/
Event Listener	Rust / Tokio + WebSocket	listener/

Features

For Token Owners

• Configure multiple vesting schedules (cliff, linear unlock, penalty, extension bonus)
• Create tiered sale phases with different prices, caps, and time windows
• Per-phase whitelists with batch management
• Treasury management with two-step ownership/treasury transfer
• Emergency pause and surplus withdrawal (user funds always protected)

For Buyers

• Buy tokens in active sale phases (pay with KLV or any KDA token)
• Tokens are atomically locked in the contract at purchase time
• Claim vested tokens after cliff period
• Extend vesting for bonus tokens (self-sustaining: penalties fund bonuses)
• Force-exit early with transparent penalty (rate locked at purchase time)
• Vesting calculator to compare scenarios before buying

Security

• Schedule terms snapshotted per position (owner cannot change terms retroactively)
• total_tokens_committed prevents owner from withdrawing user-owed funds
• pending_extension_liability reserves penalty pool for pending extensions
• Two-step ownership and treasury transfer (propose/accept)
• Economic terms locked once tokens are sold in a phase
• Batch limits on all operations, query result caps
• 3 rounds of code + security audits with 0 CRITICAL/HIGH findings

---

Quick Start

Prerequisites

• Rust with wasm32v1-none target: rustup target add wasm32v1-none
• Node.js (v18+)
• PostgreSQL
• Redis
• Klever Extension or K5 mobile wallet (for testing)

1. Smart Contract

cd contracts/meta
PATH="$HOME/.cargo/bin:$PATH" cargo run -- build

Output: contracts/output/vesting-sale-contract.wasm (~35KB)

Deploy to testnet using the Klever wallet or koperator:

• Transaction type 63 (SmartContract), scType 1 (Deploy)
• Init args: sale_token_id (hex) + precision (hex, e.g., 06 for 6 decimals)

2. Frontend

cd www
npm install
npm run dev       # Development server on http://localhost:3000
npm run build     # Production build to dist/

Create .env (never commit):

VITE_CONTRACT_ADDRESS=klv1...
VITE_NODE_URL=https://node.testnet.klever.org
VITE_API_URL=http://localhost:3001
VITE_NETWORK=testnet

3. Backend API

cd api
cp config.toml.example config.toml  # Edit with your values
cargo build --release
./target/release/klever-vesting-api

The API runs database migrations automatically on startup. Requires PostgreSQL and Redis.

See config.toml.example for all configuration options.

4. Event Listener

cd listener
cargo build --release
CONFIG_PATH=../api/config.toml ./target/release/klever-vesting-listener

Subscribes to contract events via the Klever WebSocket API and syncs purchase/claim/extension history to the database.

---

Project Structure

klever-vesting/
|-- contracts/              Smart Contract (Rust/KVM WASM)
|   |-- src/
|   |   |-- lib.rs          Main contract (init, upgrade)
|   |   |-- storage.rs      Data structures + storage mappers
|   |   |-- sale.rs         Token purchase with vesting
|   |   |-- vesting.rs      Claim, claimAll, claimBatch, extend, forceClaimAll
|   |   |-- admin.rs        Schedule/phase/whitelist/pool management
|   |   |-- query.rs        Read-only view endpoints
|   |   |-- events.rs       On-chain event definitions
|   |-- meta/               Build tooling
|   |-- wasm/               WASM adapter (auto-generated)
|   |-- output/             Build artifacts (.wasm, .abi.json)
|   |-- scripts/build.sh
|
|-- www/                    Frontend (SolidJS + Vite + TypeScript)
|   |-- src/
|   |   |-- lib/            Klever wallet, SC calls, theme, i18n, routing
|   |   |-- pages/          Home (sale), Dashboard, Calculator, Admin
|   |   |-- components/     Header, ProgressBar, CountdownTimer, etc.
|   |   |-- i18n/locales/   7 languages (EN, DE, ES, PT, JA, ZH, RU)
|   |   |-- styles/         CSS with dark/light themes
|
|-- api/                    Backend API (Rust/Axum)
|   |-- src/
|   |   |-- auth/           Klever wallet auth (Keccak-256 + Ed25519)
|   |   |-- routes/         Health, auth, sale, vesting, stats
|   |   |-- services/       Klever node/API client
|   |-- migrations/         PostgreSQL schema
|   |-- config.toml.example
|
|-- listener/               Event Listener (Rust/Tokio + WebSocket)
|   |-- src/main.rs         Auto-reconnecting chain event subscriber
|
|-- docs/specs/             Specification documents (8 files)
|-- CHANGELOG.md            Version history
|-- LICENSE                 MIT License

Documentation

Detailed specifications are in docs/specs/:

Spec	Description
01-overview	Architecture, actors, token flow
02-smart-contract	All endpoints, data structures, events
03-vesting-mechanics	Formulas, edge cases, examples
04-token-sale	Phases, pricing, whitelists
05-frontend	Pages, wallet integration, design
06-backend-api	Routes, auth flow, database
07-deployment	Build & deploy all components
08-security	Security model, hardening measures

Testnet vs Mainnet

The only difference is configuration — no code changes needed:

Setting	Testnet	Mainnet
Node URL	https://node.testnet.klever.org	https://node.mainnet.klever.org
API URL	https://api.testnet.klever.org	https://api.mainnet.klever.org

Contract address differs per deployment. URLs are never hardcoded.

Contributing

We welcome contributions from the community! Whether it's bug fixes, new features, translations, or documentation improvements — all contributions are appreciated.

How to Contribute

1. Fork this repository
2. Create a branch for your feature or fix (git checkout -b feature/my-feature)
3. Make your changes and ensure they compile:
   • Smart contract: cd contracts && cargo check
   • Frontend: cd www && npm run lint && npm run build
   • Backend: cd api && cargo check
4. Commit with a clear message describing the change
5. Open a Pull Request against master

Areas Where Help is Welcome

• Additional language translations (i18n locale files in www/src/i18n/locales/)
• Frontend improvements (animations, charts, mobile UX)
• Admin panel forms (schedule/phase creation, whitelist CSV upload)
• WalletConnect v2 integration for K5 mobile wallet
• Unit tests for smart contract and backend
• Documentation and guides
• Security reviews

Development Setup

# Clone
git clone https://github.com/Test0rMaik/Klever-Vesting.git
cd Klever-Vesting

# Smart contract
cd contracts && cargo check

# Frontend
cd www && npm install && npm run dev

# Backend (needs PostgreSQL + Redis running)
cd api && cp config.toml.example config.toml && cargo run

License

This project is licensed under the MIT License.

Version

Current version: 0.1.0 — See CHANGELOG.md for full history.