Kraflab Smart Contract Documentation - DEVELOP

Overview

Kraflab is a modular and extensible smart contract suite that facilitates:

• Role-based access control for organizations and communities
• Soulbound NFTs for identity tagging and licensing
• Secure, deterministic contract deployment using CREATE2
• Off-chain verified actions (e.g., payment, license ownership)

Monorepo Structure

kraflab-smart-contracts/
├── contracts/
│   ├── base/
│   │   └── KraflabTag.sol
│   ├── entity/
│   │   ├── Government.sol
│   │   ├── Community.sol
│   │   └── Creator.sol
│   ├── interface/
│   │   ├── IKraflab.sol
│   │   ├── IKraflabLicense.sol
│   │   └── IKraflabTag.sol
│   ├── registry/
│   │   └── ContractRegistry.sol
│   ├── Kraflab.sol
│   ├── KraflabFactory.sol
│   └── KraflabLicense.sol
├── scripts/
│   └── 1_deploy_kraflab.ts
|   └── 2_deploy_license.ts
|   └── 3_deploy_factory.ts
|   └── 4_deploy_tag.ts
├── test/
│   └── index.ts
├── config/
│   ├── ContractArguments.ts
│   └── CollectionConfig.ts
├── package.json
└── hardhat.config.ts

Quick Start (Local Development)

For immediate local development setup:

# Clone and setup
yarn install
yarn compile

# Start local blockchain
npx hardhat node &

# Deploy and configure everything in one command
npx hardhat run scripts/setup_local_all.ts --network localhost

Quick Start (Debug Mode)

For immediate debugging with enhanced logging:

# Clone and setup
yarn install
yarn compile

# Start debug node with monitor (recommended for development)
./start_debug_node.sh --debug --monitor

# In another terminal, test the setup
yarn test-debug

Installation

yarn install

Compilation

yarn compile

Test Suite

yarn test
# With gas reporting:
yarn test-gas

Local Deployment Guide

Option 1: Unified Setup Script (Recommended)

The easiest way to set up a complete local environment:

# Start local blockchain
npx hardhat node &

# Deploy and configure everything
npx hardhat run scripts/setup_local_all.ts --network localhost

This script will:

• ✅ Deploy Kraflab and KraflabLicense contracts (if not already deployed)
• ✅ Set up root permissions for the deployer
• ✅ Configure minter permissions for license creation
• ✅ Verify the complete setup

Option 2: Manual Deployment

This README explains how to deploy all smart contracts locally (on localhost) using the deploy.sh script.

1. install dependencies

   yarn install

2. compile contract first

   yarn compile

3. give executable access for the script file

   chmod +x ./deploy.sh

4. run script for localhost

   ./deploy.sh

5. you can stop or restart the script using control + c
6. you can see the log in node.log file

Quick Debug Setup

For enhanced debugging during development:

# Start with debug logging and monitoring
./start_debug_node.sh --debug --monitor

# Test the debug setup
yarn test-debug

# Deploy and configure everything with one script
npx hardhat run scripts/setup_local_all.ts --network localhost

Debug Logging & Node Monitoring

The project includes enhanced debug logging capabilities for local development:

Quick Start Scripts

# Start node with normal debug logging
yarn local-node

# Start node with detailed debug logging
yarn local-node:debug

# Start node with full debug logging (very verbose)
yarn local-node:full

# Monitor blockchain activity (run in separate terminal)
yarn monitor-node

Enhanced Debug Script

Use the convenient shell script for advanced debugging:

# Basic usage
./start_debug_node.sh

# With detailed debug logging
./start_debug_node.sh --debug

# With full debug logging (very verbose)
./start_debug_node.sh --full-debug

# Start with transaction monitor
./start_debug_node.sh --monitor

# Combine options and save logs to file
./start_debug_node.sh --debug --monitor --log-file

Debug Features

• Verbose Hardhat Logging: See internal hardhat operations
• Transaction Monitoring: Real-time transaction details and gas usage
• Block Monitoring: New block notifications with transaction counts
• Contract Interaction Logs: Detailed contract deployment and call information
• Event Logging: Automatic event decoding and display
• Account Monitoring: Balance tracking for test accounts

Log Output Includes

• Transaction hashes, gas usage, and status
• Contract deployment addresses
• Event emissions and log data
• Block information and timestamps
• Account balances and interactions
• Error details and stack traces

Use these tools to debug contract interactions, monitor gas usage, and trace transaction flows during development.

Quick Debug Workflow

1. Start Debug Node: ./start_debug_node.sh --debug --monitor
2. Test Setup: yarn test-debug
3. Deploy Contracts: yarn deploy-kraflab, yarn deploy-license, etc.
4. Monitor Activity: Real-time logs show all transactions and contract interactions
5. Debug Issues: Verbose logs help identify gas problems, failed transactions, and contract events

Contract Descriptions

Kraflab

Manages access control via modular inheritance:

• Government for managing organizations
• Community for managing groups and members
• Creator for creator identity
• Uses AccessControl from OpenZeppelin

Key Roles:

• DEFAULT_ADMIN_ROLE: Root admin
• OrgAdmin: Admin per organization
• GroupAdmin: Admin per community

KraflabTag

Soulbound ERC721 token representing a verified tag.

• Non-transferable, non-burnable (SoulboundToken error)
• Only mintable by authorized OrgAdmins
• Requires off-chain payment verification

Main Functions:

• verifyPayment(address): Marks payment as verified
• mintTag(address): Mints tag if valid, paid, and unique
• verifyTagOwnership(address): Verifies user owns a tag
• setUriTag(string): Updates metadata URI
• pause(), unpause(): Contract pausing mechanism

KraflabFactory

A deterministic factory for deploying tagged contracts using CREATE2

• Relies on license gating (KraflabLicense)
• Uses ContractRegistry for versioning

Main Functions:

• addImplementation(...): Register new implementation
• deployTag(...): Deploy a new tag contract
• predictedAddress(...): Predict deterministic address
• setActiveLicense(bool): Toggle license enforcement

KraflabLicense

ERC721 soulbound license token for granting access

• Owned by root admin
• Purchasable by government organization admins

Main Functions:

• create(...): Mint new license token
• buy(uint256, bytes32): Transfer to admin (if valid)
• checkOwnerShip(...): Validate token ownership
• setUriTag(...): Update metadata URI

Deployment Scripts

Unified Setup (Recommended)

| Ensure local node is already running.

For local development, use the unified setup script:

npx hardhat run scripts/setup_local_all.ts --network localhost

Individual Scripts

Scripts are located in scripts/:

• 1_deploy_kraflab.ts
• 2_deploy_license.ts
• 3_deploy_factory.ts
• 4_deploy_tag.ts
• setup_local_all.ts (unified local setup)

Run any script using:

yarn hardhat run scripts/1_deploy_kraflab.ts

Hardhat Tasks

Custom tasks (as defined in package.json):

yarn accounts
yarn test
yarn test-gas
yarn compile

Notes for Backend & Frontend Developers

• All smart contract roles must be verified before executing restricted functions
• Tags are soulbound; once minted, users cannot transfer, burn, or approve them
• You must call verifyPayment(account) before mintTag(account)
• You can predict clone addresses using the factory before deployment
• Tag metadata is shared across tokens via setUriTag()
• License tokens must be owned by organization admins before deploying tags if _isActiveLicense = true

Developer Tips

• Fill CollectionConfig.ts for contract arguments
• Use InstanceFactoryProvider.ts, InstanceTagProvider.ts, etc. to dynamically bind contract instances in tests
• Each organization and group is identified by a bytes32 ID (derived via keccak256(utf8("ORG1")))
• All tests are located in test/index.ts