KAM Protocol

KAM is an institutional asset management protocol that implements a dual-track architecture for both institutional and retail access. The protocol creates kTokens (kUSD, kBTC) backed 1:1 by real assets (USDC, WBTC), providing institutions with direct minting and redemption capabilities while offering retail users yield opportunities through external strategy deployment. The system features batch processing with virtual balance accounting, two-phase settlement with timelock proposals, and modular vault architecture through MultiFacetProxy routing.

For more information, refer to the architecture documentation.

Usage

KAM comes with a comprehensive set of tests written in Solidity, which can be executed using Foundry.

To install Foundry:

curl -L https://foundry.paradigm.xyz | bash

This will download foundryup. To start Foundry, run:

foundryup

To clone the repo:

git clone https://github.com/kam-protocol/kam.git && cd kam

Installing Dependencies

The project uses Soldeer for dependency management. To install all dependencies:

forge soldeer install

This will install all dependencies specified in soldeer.toml and soldeer.lock.

Building

To build the project with a more exhaustive review:

make compile

Testing

in default mode

To run the tests in a default mode:

forge test

in coverage mode

forge coverage --ir-minimum

Using solx compiler (optional)

For faster compilation with the LLVM-based Solidity compiler, you can install and use solx:

Install solx:

curl -L https://raw.githubusercontent.com/matter-labs/solx/main/install-solx | bash

Use with forge:

forge build --use $(which solx)
forge test --use $(which solx)

Smart Contracts Deployment

You can deploy to any environment(localhost/sepolia/mainnet) and get deployment addresses in deployments/output/<environment>/addresses.json. To configure deployment modify deployments/config/<environment>.json.

make deploy-localhost
make deploy-sepolia
make deploy-mainnet 

Smart Contracts Documentation

Generate and view the Foundry documentation:

forge doc --serve --port 4000

This will open the documentation at http://localhost:4000

Protocol Documentation

• Architecture - Complete protocol architecture and operational flows
• Interfaces - Interface documentation for all protocol contracts
• Audit Scope - Comprehensive audit scope and security considerations

For Integrators

Institutional Operations

Institutions can mint kTokens 1:1 with underlying assets and request redemptions through batch settlement:

• kMinter.mint() - Creates new kTokens by accepting underlying asset deposits
• kMinter.requestBurn() - Escrows kTokens and creates a redemption request for the current batch
• kMinter.burn() - Claims underlying assets from the batch receiver after settlement (kTokens already burned during settleBatch)

Retail Operations

Retail users can stake kTokens to earn yield from external strategies:

• kStakingVault.requestStake() - Request to stake kTokens for yield-bearing stkTokens
• kStakingVault.requestUnstake() - Request to unstake stkTokens back to kTokens
• kStakingVault.claimStakedShares() - Claim stkTokens after batch settlement
• kStakingVault.claimUnstakedAssets() - Claim kTokens after batch settlement

Virtual Balance System

The protocol uses virtual balance accounting to optimize gas efficiency:

• kAssetRouter maintains virtual balances between vaults and strategies
• Physical transfers occur during mint (institution → router → adapter) and settlement (adapter → batch receiver for redemptions)
• Inter-vault transfers between kMinter and staking vaults are virtual (adapter totalAssets updates only)

Batch Processing

Requests are grouped into time-based batches for gas-efficient settlement:

• Each vault manages independent batch cycles
• Batch receivers deployed per kMinter batch for isolated institutional redemption distribution
• Settlement coordinated through timelock proposals with guardian oversight and correction mechanisms

Role Hierarchy

Role	Permissions	Contracts
OWNER	Ultimate control, upgrades	All
ADMIN_ROLE	Operational management	All
EMERGENCY_ADMIN_ROLE	Emergency pause, cancel proposals	All
GUARDIAN_ROLE	Cancel/approve settlement proposals	kAssetRouter
MINTER_ROLE	Mint/burn tokens	kToken
INSTITUTION_ROLE	Mint/redeem kTokens	kMinter
RELAYER_ROLE	Propose/execute settlements, batches	kAssetRouter, kMinter, kStakingVault
VENDOR_ROLE	Grant institution roles	kRegistry
MANAGER_ROLE	Execute adapter calls	VaultAdapter
BLACKLIST_ADMIN_ROLE	Freeze/unfreeze accounts	kToken

Safety

This software is experimental and is provided "as is" and "as available".

No warranties are provided and no liability will be accepted for any loss incurred through the use of this codebase.

Always include thorough tests when using KAM to ensure it interacts correctly with your code.

Known Limitations

• Settlement proposals require timelock delays, potentially causing settlement delays if parameters need correction
• Virtual balances must remain synchronized with actual adapter holdings
• Redemption completion depends on successful batch settlement and adapter cooperation
• Adapter integrations require careful validation of different DeFi protocol settlement patterns

Contributing

The code is currently in a closed development phase. This is a proprietary protocol with restricted access.

License

(c) 2025 KAM Protocol Ltd.

All rights reserved. This project uses a proprietary license.