Klever Blockchain Skill

LLM-optimized reference for building on Klever. Use this to produce correct smart contracts, transactions, and dApp integrations.

Role

You are an expert Klever blockchain developer. Your stack:

• Smart contracts: Rust with klever_sc framework, compiled to WASM
• Client SDKs: @klever/connect (TypeScript) or klever-go-sdk (Go)
• Tooling: ksc (compiler) + koperator (deploy/invoke/query)
• Networks: Testnet for development, mainnet for production

You write clean, secure, production-ready code. You always validate against the correctness rules below before writing any code.

When to Use This Skill

Activate this skill when the task involves ANY of the following:

• KLV or KDA tokens (balances, transfers, staking, freezing)
• klv1... addresses (bech32 format)
• Klever smart contracts (Rust, klever_sc, WASM)
• ksc or koperator CLI commands
• Klever node or API interaction (ports 8080/9090)
• @klever/connect or klever-go-sdk usage

Task Decision Tree

Use this to route the task to the correct guide:

What does the task involve?
├─ Writing a smart contract?
│  ├─ New contract from scratch
│  │  └─ Start with Quick Start below, then → 01-smart-contracts.md
│  ├─ Adding storage/state
│  │  └─ → 02-storage.md (mappers, namespaces)
│  ├─ Handling tokens/payments
│  │  └─ → 03-tokens.md (payable endpoints, KLV/KDA)
│  ├─ Emitting events
│  │  └─ → 04-events.md (ONE-DATA rule)
│  └─ Using modules (admin, pause)
│     └─ → 05-modules.md
│
├─ Building or deploying?
│  └─ → 06-deployment.md (ksc build, koperator deploy/invoke/query)
│
├─ Querying on-chain data?
│  └─ → 07-api-reference.md (Node API port 8080, API proxy port 9090)
│
├─ Reviewing for security?
│  └─ → 08-security.md (reentrancy, overflow, access control)
│
└─ Debugging an error?
   └─ → 09-troubleshooting.md (common errors and fixes)

How to Use This Skill

1. Classify the task using the decision tree above
2. Validate against the correctness rules below before writing any code
3. Reference the detailed guide for the relevant topic — start minimal, add complexity only when needed
4. Verify all code uses the correct imports, address format, decimals, and CLI flags
5. Deliver complete, working code with build/deploy commands and security considerations

Klever Quick Reference

Validate all code against these facts before outputting.

• KLV decimals: 6 (1 KLV = 1,000,000 units)
• KFI decimals: 6 (same as KLV)
• KDA decimals: up to 8 (varies per asset — check the asset's precision field)
• Address format: klv1... (bech32)
• Import: use klever_sc::imports::*;
• Contract macro: #[klever_sc::contract]
• Crate: klever-sc (latest version on crates.io)
• Modules crate: klever-sc-modules (use same version as klever-sc)
• Node port: 8080 (default, configurable)
• API proxy port: 9090 (default, configurable)
• koperator payments: --values "TOKEN=amount" (plural, token=amount format)
• koperator arguments: positional — koperator sc invoke ADDRESS FUNCTION
• Event data params: max 1 non-indexed, all others must be #[indexed]

Common Mistakes

These are the most frequent errors. Check your output against this list.

1. Wrong decimal precision

KLV and KFI use 6 decimals. 1 KLV = 1,000,000 units. Never use 18 (that's EVM).

// WRONG: 18 decimals
let one_klv = BigUint::from(1_000_000_000_000_000_000u64);

// CORRECT: 6 decimals
let one_klv = BigUint::from(1_000_000u64);

2. Using --value instead of --values

koperator uses --values (plural) with token=amount format.

# WRONG
koperator sc invoke ADDR func --value 1000000

# CORRECT
koperator sc invoke ADDR func --values "KLV=1000000" --sign --await --result-only

3. Using --function flag instead of positional argument

koperator uses positional arguments, not flags, for contract address and function name.

# WRONG
koperator sc invoke --contract ADDR --function func

# CORRECT
koperator sc invoke ADDR func --sign --await --result-only

4. Multiple non-indexed event parameters

Events allow maximum ONE non-indexed parameter. All others must be #[indexed].

// WRONG: two non-indexed params — compile error
#[event("transfer")]
fn transfer_event(&self, from: &ManagedAddress, to: &ManagedAddress, amount: &BigUint);

// CORRECT: only amount is non-indexed
#[event("transfer")]
fn transfer_event(
    &self,
    #[indexed] from: &ManagedAddress,
    #[indexed] to: &ManagedAddress,
    amount: &BigUint,  // only non-indexed param
);

5. BigUint subtraction without validation

BigUint panics on underflow. Always check before subtracting.

// WRONG: aborts if balance < amount
self.balance(&user).update(|b| *b -= &amount);

// CORRECT: validate first
require!(balance >= amount, "Insufficient balance");
self.balance(&user).update(|b| *b -= &amount);

6. Missing #[upgrade] endpoint

Upgradeable contracts must define an #[upgrade] function. Without it, contract upgrades will fail.

#[upgrade]
fn upgrade(&self) {}

Quick Start

Project Setup (Cargo.toml)

[package]
name = "my-contract"
version = "0.1.0"
edition = "2021"

[lib]
path = "src/lib.rs"

[dependencies.klever-sc]
version = "0.45.1"  # use latest from crates.io

[dev-dependencies.klever-sc-scenario]
version = "0.45.1"  # use latest from crates.io

Minimal Contract

#![no_std]
use klever_sc::imports::*;

#[klever_sc::contract]
pub trait MyContract {
    #[init]
    fn init(&self) {}

    #[upgrade]
    fn upgrade(&self) {}

    #[endpoint]
    fn set_value(&self, value: u64) {
        self.stored_value().set(value);
    }

    #[view(getValue)]
    fn get_value(&self) -> u64 {
        self.stored_value().get()
    }

    #[storage_mapper("storedValue")]
    fn stored_value(&self) -> SingleValueMapper<u64>;
}

Build & Deploy

# Update dependencies (after bumping versions in Cargo.toml)
~/klever-sdk/ksc all update

# Build
~/klever-sdk/ksc all build

# Deploy
~/klever-sdk/koperator sc create \
    --wasm="output/contract.wasm" \
    --upgradeable --readable --payable --payableBySC \
    --sign --await --result-only

Invoke & Query

# State-changing call (invoke)
~/klever-sdk/koperator sc invoke CONTRACT_ADDR set_value \
    --args "u64:42" \
    --sign --await --result-only

# Read-only call (query)
~/klever-sdk/koperator sc query CONTRACT_ADDR getValue

Argument Types for koperator

Networks

Detailed Guides

1. Smart Contracts -- Contract structure, endpoints, lifecycle
2. Storage -- All mapper types, namespaces, patterns
3. Tokens & Payments -- KLV/KDA handling, payable endpoints
4. Events -- Event definitions, the ONE-DATA rule
5. Modules -- Admin, Pause, custom modules
6. Build & Deploy -- ksc, koperator, scripts
7. API Reference -- Node and API proxy endpoints
8. Security & Best Practices -- Common vulnerabilities, patterns
9. Troubleshooting -- Common errors and fixes

MCP Server

For AI-assisted development, connect to the Klever MCP Server:

# npm (local stdio mode)
npx @klever/mcp-server

# Docker
docker run -p 3000:3000 kleverapp/mcp-klever-vm:latest

# Remote (no install)
# URL: https://mcp.klever.org/mcp

Knowledge tools: search_documentation, query_context, get_context, find_similar, get_knowledge_stats, enhance_with_context, analyze_contract

Project tools: init_klever_project, add_helper_scripts

Other tools: add_context