Skip to content
Cosmic

Documentation

How Cosmic works.

This page describes what the contracts do, in the order you meet it. It is a description of code, not a promise: nothing here is a yield, a rate or a guarantee of price or return.

What Cosmic is

Cosmic locks ERC-20 tokens for a period you choose. A vault exists for each supported token. When you lock, the vault records a position: your address, the exact amount it received, when it started and when it matures. Positions belong to the address that created them and cannot be transferred.

Three things can happen to a position's token beyond simply getting it back. An early exit pays a penalty. Part of every penalty is shared with other lockers of the same token. And a project can pay lockers of a token through a campaign. The rest of each penalty accumulates in a reserve used to buy and burn COSM.

The two lock types

Flexible lock

You may leave before maturity. The contract keeps an early-exit penalty and returns the rest of your principal. Leaving early also gives up the community rewards the position has been allocated so far, and any campaign reward it reserved.

Commitment lock

You may not leave before maturity. This is not a setting: the early-exit function rejects Commitment positions, and no account, including the contract owner, has a function that releases one. At maturity the full principal is yours to withdraw.

Both types are eligible for community rewards on the same footing: a position's weight is its principal, whatever its type or duration.

Time and maturity

The contract measures time with the chain's block timestamp. Time is divided into epochs of a fixed length. When you lock for a duration:

  • Maturity is the first epoch boundary at or after the start plus the duration. A lock is never shorter than the duration you chose, and at most one epoch longer.
  • Activation, the moment the position starts sharing in penalties, is the first epoch boundary strictly after the lock was created, plus any seasoning the vault's terms require.
  • A position is mature from the maturity second on. Withdrawal is possible from that second, with no penalty, for both lock types.

The app shows maturity in your time zone and in UTC and counts down using the chain's clock. Your device's clock is only a display aid; the contract decides.

The early-exit penalty

The penalty is a share of the principal. It is highest when the lock starts and falls in a straight line to its lowest value at maturity. Both values belong to the vault's terms. Terms are versioned: a position keeps the version it was created under, and publishing a new version changes nothing for existing positions.

L = maturity - start          R = maturity - now

penalty = ceil( principal * (min * L + (max - min) * R) / (10 000 * L) )
you receive = principal - penalty

The penalty is rounded up to the token's smallest unit. Before you sign, the app reads a quote from the contract: principal, penalty, what you receive, and what you forfeit. The transaction carries the payout you accepted as its minimum and a deadline; if the contract would pay less, it reverts and nothing changes.

Community rewards

When a Flexible position exits early, part of its penalty is allocated to the positions that are eligible at that moment.

D = min( floor(penalty * share), floor(exiting principal * cap) )
  • Share is at most 90%. The contract refuses terms with a higher share.
  • Cap limits the allocation relative to the exiting principal.
  • D is the total for that exit. It is divided among eligible positions in proportion to their principal. It is not an amount per position and not a return on anyone's deposit.
  • The remainder of the penalty goes to the vault's buyback reserve. If nobody is eligible, the whole penalty goes there.

Who is eligible

  • Positions of the same vault, which means the same token.
  • Active and past their activation, and not yet mature. A position that has matured is excluded even if it has not been withdrawn.
  • Not the exiting position itself.
  • A position created in the same block as the exit is never eligible for it: its activation is still in the future.

Conditional, then vested

What a position has been allocated is conditional until its own maturity. If it exits early, the amount is forfeited and moves to the buyback reserve; it is not redistributed. From maturity on the amount is vested: final, unaffected by later exits, and paid together with the principal by a single withdrawal. A position that withdraws late keeps what it earned and earns nothing more.

How the accounting scales

No transaction loops over positions. Each vault keeps a running figure of penalties allocated per unit of eligible principal, and because activation and maturity fall on epoch boundaries, the eligible total only changes on boundaries and at exits. Boundaries are applied lazily by a checkpoint that anyone can call and that every exit performs first. A matured withdrawal never depends on it.

Campaigns

A campaign is a sponsor's budget, in escrow, paid at a fixed rate to positions that stay until maturity.

  • The sponsor creates the campaign for one vault and transfers the whole budget in the same transaction. A campaign without funds cannot exist.
  • The campaign states a reward per locked token, a window, and requirements: lock type, minimum lock duration, minimum principal.
  • The owner of an eligible position enrols it during the window. Enrolling reserves the reward from the unreserved budget, first come first served. If less remains than the full reward, only the remainder is reserved, and you can decline.
  • The reward is paid once, to the position's owner, when the position is mature and did not exit early.
  • If the position exits early, anyone can release its reservation back to the budget.
  • After the window the sponsor can recover what is unreserved. Reserved amounts cannot be recovered.

Anyone can sponsor a campaign in an allowed reward token. A campaign is identified by its sponsor's address; a label, if present, is text written by the sponsor. Funding a campaign with a project's token does not make it official.

Buyback and burn

Each vault's buyback reserve holds the part of penalties not allocated to lockers, plus forfeited allocations. It is separate from principal and from the community reserve.

  • Only the buyback module can take a reserve, and only the reserve. The module address can be set once.
  • An operator executes a buyback with an amount, a minimum of COSM to receive, a deadline and an authorised route. The module measures the COSM it actually received and burns exactly that.
  • If the swap fails or delivers less than the minimum, the reserve does not leave the vault and the attempt is recorded as failed.
  • Penalties from a COSM vault are already COSM and are burned directly, without a swap.
  • The module has no price oracle. The minimum the operator signs is the only price bound, which makes the operator a trusted role.

A reserve is not a buyback. The transparency page lists, separately, what is set aside, what was spent, the COSM received, and the COSM burned. Where no route is configured the reserve waits, and the page says awaiting execution configuration.

The COSM token

COSM is the protocol's own token. The contracts give it two parts and no others.

  • It is what the reserve is spent on. The part of every early-exit penalty that is not allocated to eligible lockers goes to a buyback reserve. The buyback module spends that reserve to buy COSM and burns the COSM it received. Every execution is a transaction on chain.
  • It can be locked. COSM can be locked in its own vault like any supported token. The reserve of a COSM vault is already COSM and is burned directly, without a swap.

Locking another token does not require COSM, and community rewards are paid in the token of the vault they come from. How COSM is destroyed is fixed when the buyback module is deployed: either the token's own burn function, which lowers total supply, or a transfer to an irrecoverable address, which does not. The transparency page reports the two separately.

The contract address

The site currently says CA: Soon. It means the contract address of COSM has not been published yet. When it is, it appears on this site first: on the landing page, in the footer of every page and at /api/token.

The only official address is the one shown on this site. An address from any other source, whatever name or logo it carries, is not COSM. Compare every character before you use one.

The official account

Cosmic has one official social account: @CosmicHood_ on X. An address posted anywhere else, including in replies to that account, is not a source. The address to rely on is the one on this site.

Supported tokens

A vault exists only for a token the owner has added. The first version supports standard ERC-20 tokens. On deposit the vault compares its balance before and after and rejects the deposit unless it received exactly the amount sent, which excludes tokens that charge a fee on transfer. Rebasing tokens cannot be detected on chain and are not supported; listing is an owner responsibility.

Who can do what

  • The vault owner can add a supported token, publish new terms for future positions, pause and resume new deposits of a vault, and set the buyback module once.
  • The vault owner cannot withdraw or move principal, touch the community reserve, change the terms of an existing position, block an exit or a matured withdrawal, or upgrade the contract. There is no proxy.
  • The buyback owner names operators and authorises routes. A new route becomes usable only after a fixed delay.
  • The campaigns owner keeps the reward-token allowlist. It cannot move campaign funds.

Where the numbers come from

Balances, positions, terms, quotes and totals are read from the contracts, all at one block, and each page states that block and how long ago it was read. Transaction history and hashes come from this app's event index, which states how far it has indexed and compares its sums with the contracts' own counters. Amounts are shown in each token's own units. They are not converted to a currency and never added across tokens.

Limits and risks

  • The contracts have not been audited.
  • Community rewards depend on other people exiting early and on who is eligible then. They can be zero.
  • Waiting one epoch before sharing prevents entering and capturing a penalty in the same block. It does not remove every timing strategy.
  • A Commitment lock cannot be undone. If you may need the tokens before maturity, it is the wrong lock.
  • Buyback execution depends on an operator and on liquidity existing for COSM.

This deployment

  • Network: Robinhood Chain, chain id 4663.
  • The Cosmic contracts are not deployed on this network. The app shows that state instead of data.