Kopi

We express our gratitude to the Kopi team for the collaborative engagement that enabled the execution of this Blockchain Protocol Security Assessment.

Kopi is a Cosmos-SDK-based protocol featuring a flexible TokenFactory module for on-chain custom asset issuance, metadata management, and seamless liquidity integration.

The system users should acknowledge all the risks summed up in the risks section of the report

Documentation quality

• Provides clear guidance for end-users; however, additional detail for developers would enhance usability.

• Presents strong conceptual framing, though it would benefit from the inclusion of formal specifications.

• Follows a logical structure, but lacks a high-level architectural overview.

• Aligned with the current codebase version, yet includes limited inline documentation.

• Features readable and well-written prose, though offering more practical examples would further improve clarity.

Code quality

• Effectively reuses Cosmos-SDK patterns, with some opportunities to reduce duplication. Keeper methods, message handlers, and collection wiring align well with standard SDK idioms, offering immediate familiarity for Cosmos-SDK developers.

• Employs well-structured cache prefixes. The use of typed collections.Prefix constants with cache.New creates clear and strongly-typed storage namespaces.

• Demonstrates strong typing and well-defined domain models.

• The code is generally readable and idiomatic Go, though a few minor naming inconsistencies remain.

• Maintains a lean dependency footprint. While schema setup can be verbose, it is clear and explicit.

• Inline documentation is limited but partially offset by clear, self-documenting code structure.

Architecture quality

• Modular, Cosmos-SDK–native design. Tokenfactory plugs cleanly into the Cosmos-SDK keeper/model framework, inheriting its well-understood module lifecycle, upgrade path, and governance hooks.

• In-chain performance & scalability. All Tokenfactory logic runs on the existing Tendermint-powered chain, so it benefits from Cosmos’s low-latency, high-throughput consensus without adding extra inter-module hops.

• Clear separation of concerns. State management (via collections), business logic (in keeper methods), and parameter tuning (via on-chain Params) are neatly layered, making each component easier to reason about and test.

• Limited observability & metrics. There’s no built-in telemetry for critical flows (e.g. mint/burn rates, rate-limit breaches), so you’ll need external instrumentation to monitor performance and anomalies.

Test coverage

Code coverage of the project is ~30% and mutation score of ~60%

• Branch coverage is primarily focused on happy paths; error-handling branches (e.g., if err != nil or negative conditions) are generally not exercised in tests.

• Critical edge cases and negative scenarios are underrepresented - many Err... conditions in keeper logic and message validation remain untested.

• Potential issues with cache and prefix usage are not currently covered by tests.

The Tokenfactory is the on-chain minting and metadata subsystem in the Kopi protocol, built as a Cosmos-SDK module. It lets users spin up fully on-chain custom tokens, control their lifecycle (minting, metadata updates, admin changes), and wire them into decentralized liquidity pools. All state is managed via the module’s keeper and persisted using the Cosmos-SDK collections framework.

Core Responsibilities

Token Issuance Supply Control

• Users (the “creator”/admin) call MsgCreateDenom to mint an initial supply of a new “factory” token.

• Post-creation, they can mint or burn further units (if allowed) via module messages.

Metadata Management

• Through MsgUpdateDescription, MsgUpdateWebsite, and MsgUpdateIconHash, admins can tweak human-readable fields (description text, website URL, image hash), subject to on-chain rate limits.

Permissioned Admin Role

• Each token has an on-chain Admin address. Ownership can be transferred with MsgChangeAdmin, guaranteeing only the current admin may update supply or metadata.

Custom Liquidity Pools

• Optionally at creation (or any time later), a new factory token can be paired against the protocol’s base kCoin in a Constant Product pool (x/tokenfactory pools), enabling trading via the DEX keeper.

Fee Reserve Mechanics

• Every trade routed through a Tokenfactory pool splits fees between the liquidity pool and the protocol reserve, according to on-chain parameters.

Major Components

Keeper

• Orchestrates state reads/writes via typed collections.Prefix caches (denoms, pools, offers, vestings, etc.)

• Implements handlers for all tokenfactory messages (create, update, trade, admin change).

Types Messages

• FactoryDenom struct: on-chain record of token supply, admin, metadata, and timing-windows.

• LiquidityPool struct: reserves of kCoin vs. factory token, fee parameters, reserve-fee share.

• Proto messages (MsgCreateDenom, MsgSell/MsgBuy, etc.) with ValidateBasic logic.

Parameters from onchain Params

• MaxDenomNameLength, MaxDescriptionLength, MaxWebsiteLength: enforce metadata size limits.

• ChangeSecondsDescription, ChangeSecondsWebsite, ChangeSecondsImage: rate-limit how often metadata can be updated.

• ReserveFeeShare: fraction of trade fees that goes to the protocol reserve vs. the pool.

Auxiliary Modules

• BankKeeper: mints/burns coins and moves them between accounts and module accounts.

• DexKeeper: if using the DEX abstraction for cross-token trades.

• Reserve module: for storing protocol revenues.

The scope of the project includes the following components from the provided repository:

Components in Scope

The entire tokenfactory module.

• Message Definitions & Validation

• Keeper Logic & State Management

• Persistence Layer & Prefixes

• Trading & Fee Mechanics

• Metadata Updates & Rate-Limits