Liquidity mechanics

Klineo turns a project's liquidity objectives into capital comparisons, simulation evidence, bounded proposals, and recorded outcomes. Planning and analysis can help a team review its options before funding a vault. A proposal can move assets only through the separate approval, release, policy, and execution checks described in Decisions and execution.

Read amounts correctly#

Token amounts travel through the SDKs and API as atomic integer strings. An atomic amount is the smallest representable token unit. Keep these values as strings or bigint; converting them to JavaScript number can lose precision.

One pip equals 0.0001 percentage points. Pips are different from basis points: 100 pips equals 1 basis point. The field determines the meaning of the percentage: a confidence, inventory allocation, slippage cap, and reserve ratio share a scale but measure different things.

import {
  applyPips,
  parseAtomic,
  parseDecimalToAtomic,
} from '@klineo/liquidity-core';

const quoteAmount = parseDecimalToAtomic('25.5', 6); // "25500000"
const onePercent = applyPips(parseAtomic(quoteAmount), 10_000);
console.log(onePercent.toString()); // "255000"

Decimal parsing rejects negative values, scientific notation, noncanonical numbers, and more fractional digits than the asset allows. The shared helpers use integer arithmetic with explicit rounding. Accounting valuation normally rounds down; a minimum token-sale price rounds the required quote output up so that truncation cannot weaken the issuer's price floor.

Capital, reserves, and executable depth#

The vault's accounted value includes idle project tokens, idle quote assets, deployed position principal, and accrued fees, using an authenticated reference price. A protected quote reserve is an idle quote sleeve excluded from deployable capital. It is not an investment return or a promise that the quote asset will retain its value.

The active-liquidity ratio is:

active in-range principal valued in quote
---------------------------------------
accounted vault value - protected quote reserve

Only principal in ranges containing the finalized spot tick contributes to the numerator. Accrued fees contribute to accounted value but become active liquidity only when collected and deliberately redeployed. Proposed position minima are used for conservative post-action checks; desired maximum amounts do not establish that the floor will be met.

Pool TVL and executable depth answer different questions. TVL totals assets; concentrated-liquidity depth measures how much a trade can consume inside a price band. Where available, the finalized snapshot's directional depth uses a V3 tick walk inside a fixed 2% spot-price band. Buying project tokens reports gross quote input including the pool fee; selling project tokens reports available quote output. Review both directions when evaluating market quality.

From issuer intent to capital variants#

An issuer intent declares a target trade size, maximum slippage, executable-depth objective, capital ceiling, reserve requirements, and operating constraints. The capital calculator uses a versioned local-depth approximation:

slippage capital = ceil(target trade size × 1,000,000 / maximum slippage pips)
depth capital = ceil(target executable depth × (1,000,000 + depth-band pips) / 1,000,000)
minimum capital = max(slippage capital, depth capital)

The output compares five variants: CURRENT, RECOMMENDED, CONSERVATIVE, CAPITAL_EFFICIENT, and EMERGENCY. Each reports required and deployable capital, stable and emergency reserves, modeled range width, slippage, fee estimates, and whether it satisfies the intent.

Names alone do not establish suitability. Review satisfiesIntent, its reasons, and the declared capital ceiling. Comparison variants can fail the intent. Fee estimates are formula outputs under the stated assumptions; they are not committed income. Use simulation to explore stress behavior and venue-specific evidence before progressing to a policy.

Built-in strategies#

Bootstrap needs inventory on both sides and sufficient capital to restore the active-liquidity floor. If no valid range or bounded amount fits, it returns NO_ACTION. Maintain prioritizes an out-of-range position and can close that position, perform a bounded inventory swap, and mint its replacement atomically. Otherwise it compares reconciled inventory, including deployed principal and accrued fees, with the configured target and threshold.

The current Diversify engine is diversify-exact-input-1.0.0. It requires issuer-Safe approval. Its mandate includes total, daily, and hourly token-sale caps, an organic-volume participation limit, a minimum sale price, retained-token minimum, expiry, and disclosure commitments. Quote proceeds follow PROTECTED_QUOTE_RESERVE; repurchases are disabled. Backend admission checks current evidence and remaining allowances in addition to the strategy's candidate calculation. Older passive Diversify versions are retained only to close existing sleeves.

A strategy result may be NO_ACTION, PAUSE_RECOMMENDATION, RECOMMENDATION, or CANDIDATE_PROPOSAL. Read the reason and evidence together. A recommendation is a calculation to review; it does not carry transaction authority.

Policy boundaries#

An active policy binds the strategy version and configuration, validity window, allowed pools and recipients, executor and guardian, range widths, position count, quote reserve, liquidity floor, swap sizes, slippage, daily turnover, action frequency, gas reimbursement, and realized-loss budget.

For value-protected actions, the source check requires independent primary oracle, secondary oracle, and pool TWAP observations. The reference valuation is the integer mean of the two oracle prices; pool TWAP is a deviation witness. Source identity, confidence, observation age, and configured price deviations are checked. The immutable minimum confidence floor is 800,000 pips. Confidence is an admission threshold, not the probability of a profitable outcome.

The shared evaluator returns an explicit allow or deny result such as SOURCE_UNSAFE, COOLDOWN_ACTIVE, QUOTE_RESERVE_BREACH, SLIPPAGE_LIMIT, or POSITION_CAP. Use the reason to correct inputs or seek an authorized policy change. A client calculation cannot override the live controller's checks.

Use the app#

Start with a project and its evidence, record the issuer intent, and compare capital variants. Inspect simulations, costs, reserve behavior, and source lineage. Review the policy and proposed action before using the separate approval workflow. After submission, follow finality and reconciliation rather than treating a transaction hash as a completed result.

Klineo's implemented math and contract workflows do not establish a live production release. The checked-in canonical release manifests currently disable activation. Availability of funding or execution depends on the running environment's verified release and capability gates.