Contracts overview
The seven KIMP core contracts on GIWA, their responsibilities, how they call each other, and who can change or pause them.
KIMP is seven Solidity contracts deployed on GIWA. They are written for Solidity ^0.8.24, are non-upgradeable, and share two access roles: the governance timelock, which sets parameters, and the guardian Safe, which can only pause.
Contracts#
| Contract | Responsibility |
|---|---|
KimpIndex | Stores the finalized Kimp Index per asset and epoch. Computes the median, applies quorum, staleness and the circuit guard. Serves latest and twap. Holds the source switch setSource. |
KimpReporterRegistry | Reporter bonds in $KIMP, report submission, automatic flagging, disputes and slashing. Forwards valid reports to KimpIndex. |
KimpMarket | Kimp Contracts. open, increase, close, settle, redeem, liquidate. Margin, leverage, limits, fees and per-asset market state. |
KimpPool | The LP vault and counterparty. Escrows trader margin, holds liquidity, issues kLP, computes NAV, manages the withdrawal queue. |
KimpVerifiedGate | Reads DojangScroll.isVerified for the Verified Lane. Stores the leaderboard opt-in flag. |
KimpStaking | $KIMP staking, the 30% fee share, reporter payments, unstake cooldown, voting weight. |
KimpBuyback | Accumulates 20% of fees, swaps to $KIMP with a TWAP guard, burns. |
The $KIMP token, the governor, the timelock and the fair launch contract are deployed alongside them. See Mainnet deployment plan.
Call graph#
- 1Reporters call
KimpReporterRegistry.submitonce per epoch with signed reports for each asset. - 2The registry checks bond status and signatures, then forwards reports to
KimpIndex. - 3
KimpIndexfinalizes each epoch: median of valid reports, quorum of 5, circuit guard above 300 bps. - 4Traders call
KimpMarket.open. For the Verified Lane, the market first callsKimpVerifiedGate. - 5
KimpMarketreadsKimpIndex.latestfor entry, checks caps againstKimpPool.nav, and moves margin into pool escrow. - 6Fees are split at collection: 50% to
KimpPool, 30% toKimpStaking, 20% toKimpBuyback. - 7At expiry, anyone calls
KimpMarket.settle, which readsKimpIndex.twapover the final hour and books P&L against the pool. - 8Keepers call
KimpMarket.liquidateon under-margined positions and receive 10% of the penalty.
Access control#
| Role | Holder | Powers |
|---|---|---|
onlyTimelock | Governance timelock, 48-hour delay | Every parameter setter, including setSource, caps, fees, limits |
onlyGuardian | Safe multisig, 4-of-7 | Pause and unpause markets. Nothing else. |
onlyMarket | KimpMarket | Pool escrow and payout, fee notifications |
onlyRegistry | KimpReporterRegistry | Report forwarding into KimpIndex |
| Permissionless | Anyone | Trading, deposits, staking, settle, liquidate, execute, disputes |
No role can transfer user funds out of the pool, change a position, or mint $KIMP.
Upgrade policy#
Core contracts are non-upgradeable. There are no proxies on custody logic. Contract references between core contracts are immutable where they carry custody, and timelocked where they do not. When a new version is needed, it is deployed side by side and governance votes to migrate. Existing positions settle on the contracts they were opened on. See Admin keys and timelock.
Units and conventions#
| Quantity | Type | Unit |
|---|---|---|
| Index value | int256 | Basis points, signed. Negative values are a reverse premium. |
| USD amounts | uint256 | 18 decimals |
| Timestamps | uint64 | Unix seconds |
| Asset identifier | bytes32 | Ticker, for example "BTC" |
| Epoch | uint64 | Unix minute, 60 seconds each |
GIWA dependencies#
- 1-second blocks and Flashblocks preconfirmations for fast feedback. See Flashblocks usage.
- DojangScroll and the EAS predeploy for the Verified Lane. See Dojang integration.
- An on-chain GIWA DEX for buyback execution.
- The Upbit Oracle, once it ships on GIWA, as primary Upbit price source.
Full signatures are in Interfaces.