Documentation

docs_

Everything PAPERVAULT does, in plain language. If something here and the contract disagree, the contract wins — the addresses are at the bottom.

1. What PAPERVAULT is

PAPERVAULT is an ERC-20 token on HyperEVM. Its only market is a Uniswap v4 pool where it trades against PAPER, the token of PaperTrade. The liquidity in that pool is owned by the vault contract and can never be withdrawn by anyone.

Because the pool's PAPER can only grow, each PAPERVAULT token has a guaranteed minimum value in PAPER: the Hard Floor. Everything else in the system — fees, staking, bonds, loans — is built to push that floor up and to reward people who hold through it.

In one line: a token whose backing cannot go down, that pays its stakers every time the backing goes up.

2. The locked pool

At launch the full PAPERVAULT supply is paired with seed PAPER into a single full-range Uniswap v4 position. The position is held by the hook contract, which has no function to remove it. There is no LP token, no owner, no upgrade path.

  • The pool charges 0% LP fee at the Uniswap level. All fees are taken by the hook (section 4).
  • The hook refuses any swap that would settle below the Hard Floor (section 3).
  • The hook is the only contract that can add to the position, and it only ever adds — from fees, bonds and loan fees.

3. The Hard Floor

The Hard Floor is the amount of PAPER that is permanently committed to backing each PAPERVAULT token. Roughly:

Hard Floor (PAPER per PAPERVAULT) = PAPER permanently in the pool ÷ PAPERVAULT supply the pool has to buy back

Four things raise it, nothing lowers it:

  • Trading fees — 2% of every buy and sell is added to the pool.
  • Bonds — the PAPER paid for a bond goes into the pool at a price above backing.
  • Loan fees — the 0.5% per-term fee goes into the pool.
  • Burns — loan defaults burn collateral, which lowers the supply the pool has to back.

Market price can be above the floor (the difference is the premium) but the hook will not let a trade cross below it. The stats strip on every page shows both numbers side by side.

4. Fees

Every buy and every sell pays 5% of the trade, taken by the hook in the token being paid in:

ShareGoes toChangeable?
2%compounded into the locked pool — raises the Hard Floorno, immutable
3%ops treasury — team, integrations, listingsdestination can be re-routed via a timelocked connector; the 3% itself cannot be raised

There are no other fees: no transfer tax, no claim fee, no unstake fee.

5. Buying and selling

Use the Buy / Sell panel. “Buy PAPERVAULT” takes PAPER from your wallet (after a one-time approval) and sends PAPERVAULT back. “Sell PAPERVAULT” does the reverse. The panel shows the rate, the fee split, the minimum you will receive at 1% slippage, and the Hard Floor so you can see how much premium you are paying.

Transactions time out after 10 minutes if not mined. Nothing you buy is locked; sell whenever you like.

6. Staking

Staking has no lock. The rules:

  • Warm-up: 6 hours after staking before you start earning (from the next epoch after warm-up ends).
  • Cooldown: when you press “Start unstake”, that amount stops earning and becomes withdrawable 6 hours later via “Withdraw PAPERVAULT”.
  • Loyalty boost: 1× for the first 2 days, 1.5× from day 2, 2× from day 5, 2.5× from day 7. The boost counts continuous staking time and resets to 1× on any unstake. Adding to a stake does not reset it.
  • Permanent stake: optional. Tokens can never be unstaked. Earns at a flat 4×.
  • Claim rewards: any time. Rewards are paid in PAPERVAULT (and in any extra reward token added via a connector).
weight = amount × boost your share = your weight ÷ total weight epoch reward = your share × tokens minted this epoch

7. Emissions (the ratchet)

PAPERVAULT has no inflation schedule. New tokens exist only because the floor went up. The mechanism is called the ratchet:

  1. Time is divided into 6-hour epochs.
  2. At each epoch boundary anyone may poke the ratchet (the site does this automatically for the first visitor; it costs only gas).
  3. The ratchet compares the current Hard Floor with the mark — the highest floor it has ever recorded.
  4. If the floor is above the mark, it mints PAPERVAULT to the staking contract. The amount is sized to the rise so that, after minting, backing per token is still at least the new floor. The mark is then set to the new floor.
  5. If the floor is not above the mark, nothing is minted.

Consequences: emissions can be zero for many epochs in a quiet market and large in a busy one; emissions never push the floor down; and the APR shown on the site is a trailing estimate, not a promise.

8. Bonds

A bond lets you buy PAPERVAULT from the protocol at a discount to market, paying in PAPER that goes straight into the locked pool. You receive the tokens as a stake locked for the term, earning from the next epoch:

TermDiscount to marketDelivered as
12 hours10%stake locked 12h, then 6h cooldown
24 hours20%stake locked 24h, then 6h cooldown
48 hours30%stake locked 48h, then 6h cooldown

Three terms: 12h → 10% off, 24h → 20% off, 48h → 30% off the lower of the 10-minute TWAP and spot. Cap: tokens out = min(market × (1 + discount), PAPER ÷ backing per token), so no bond can lower backing. Bonds never close; near backing the effective discount shrinks and the panel shows the real number. Tokens are delivered as a stake that earns from the next epoch and cannot unstake until the term ends.

A bond never resets your loyalty boost. The vested part of a bond stake can be unstaked like any other stake (6h cooldown).

9. Cooler loans

Borrow PAPER against PAPERVAULT without ever risking liquidation.

  • Amount: up to 95% of the Hard Floor value of your collateral, in PAPER.
  • Term: 30 days. Fee: 0.5% of principal per term, added to the debt, paid into the locked pool when you repay or roll.
  • Repay loan: send principal + fee at any time before the due date; collateral is returned in the same transaction.
  • Roll: pay just the 0.5% fee before the due date and the term restarts.
  • Default: after the due date with no repayment or roll, anyone can close the loan. Collateral is burned, the debt is cancelled, the borrower keeps the PAPER. No liquidator, no auction, no penalty beyond the lost collateral.

Why this is safe: the loan is sized against PAPER that is already in the pool and cannot leave, not against market price. A default removes tokens from supply while the PAPER stays, so backing per remaining token goes up. Locked collateral does not earn staking rewards.

10. Connectors

The core is immutable. Growth happens through four connector slots, each with a hard cap in the contract and a public delay (timelock) before activation:

SlotPurposeDelayHard limit
Reward tokensstream an extra token (e.g. PAPER) to stakers72 hcannot touch PAPERVAULT supply or the pool
Mint modulesnew issuance paths (e.g. partner bonds)7 daysglobal supply cap; must keep backing ≥ floor
Fee sinkswhere the ops 3% is sent72 hshare fixed at 3%; cannot touch the 2% floor share
Hook extensionsextra swap-time logic7 dayscannot remove liquidity, lower the floor or change fees

Every proposal is on-chain and visible for the full delay. The delays and caps are themselves immutable.

11. Trust assumptions

  • Never changeable: LP lock; 5% fee; 2% / 3% split; Hard Floor accounting; mint rule; loan terms (95% / 30 d / 0.5% / no liquidation); connector delays and caps.
  • Operated by the team: the ops treasury wallet (receives the 3%), proposing connectors (subject to delay and caps), running the website.
  • External dependencies: Uniswap v4 PoolManager on HyperEVM; the PAPER token contract; the HyperEVM chain itself. PAPERVAULT uses no price oracle.
  • What the website is: a static front-end. It reads from the public RPC and sends transactions through your wallet. It holds no keys and no user data. You can interact with the contracts directly from the explorer without it.

12. Wallet & network

  • Network: HyperEVM, chain id 999, RPC https://rpc.hyperliquid.xyz/evm, explorer https://hyperevmscan.io. Gas is paid in HYPE.
  • Wallets: any browser or mobile wallet that injects window.ethereum (MetaMask, Rabby, OKX, Coinbase Wallet…). Press “Connect wallet”; the site asks the wallet to switch to HyperEVM and adds the network if it is missing.
  • Approvals: the first buy, bond, repay or roll asks you to approve PAPER; the first sell, stake or borrow asks you to approve PAPERVAULT. Approvals are for the exact amount of the action.
  • Every transaction link on the site opens on hyperevmscan.io.

13. Glossary

  • PAPER — PaperTrade's token; the pair asset and the unit the floor is measured in.
  • Hard Floor — PAPER per PAPERVAULT guaranteed by the locked pool. Only rises.
  • Premium — price ÷ floor − 1. The room a bond discount has.
  • Epoch — a 6-hour window; emissions are decided at its end.
  • Mark — highest floor ever recorded by the ratchet.
  • Ratchet — the contract that mints to stakers when the floor beats the mark.
  • Boost — multiplier on your stake weight from continuous staking time (1× → 2.5×) or permanent stake (4×).
  • Warm-up / cooldown — the 6-hour waits on the way into and out of staking.
  • Cooler loan — a fixed-term, no-liquidation loan against the floor.
  • Connector — a timelocked, capped extension slot.

14. Contracts

Addresses are loaded from papervault.json. Empty rows mean the contract is not deployed yet and the site is in preview mode.