ZXO Protocol

1. Project overview

ZXO exists so a person can provide concentrated liquidity on a Uniswap V3–compatible pool and earn two things at once: the pool’s trading fees (the ordinary V3 LP return) and a protocol emission paid in a freshly deployed ZxoToken that is itself one side of that pool.

The farm does not take custody of loose tokens as a vault balance the owner can rewrite. On stake, ZXO mints a fee-tier 100 position NFT to itself, books the position, and later returns that exact NFT. Rewards are minted at claim time against immutable per-pool ceilings. There is no pause switch on unstake.

2. Problem statement

Most on-chain “farms” fail one of four tests:

• Custody. The contract holds raw balances an admin can sweep.
• Uncapped mint. Reward token supply is a political knob with no hard ceiling after launch.
• Frozen exits. A pause, a health check, or an upgrade proxy can trap principal.
• Mercenary liquidity. Full-range or off-range LP earns emissions without actually making a market near the price people trade.

ZXO is built against those four. Principal is an NFT the owner cannot transfer. Caps are packed at createPool and have no raise path. Unstake ignores the health gate. Emissions are weighted toward in-range, two-sided liquidity via a composition bonus, and claims themselves require the pool tick to sit inside the user range (spot tick, not TWAP — accepted risk M-02).

3. Solution summary

Each pool is a pair of a new ZxoToken and an external pair token (USDC-class 6 decimals, BTC-class 8, or 18). The protocol seeds a large single-sided core LP just off 1:1 as a sell wall, books a narrower core-stake position that soaks part of the emission weight and never claims, then opens user staking on a ±300-tick band around parity at the 0.01% fee tier.

Reward rate is retargeted at most once per hour from TVL and a target APR, then clipped by two immutable caps: a bps cap (maxNormalAPR, doubled during the first year) and a 30-day token cap (max30dRate). Users who pair more of the external token than the ZXO token, above a 50% paired-ratio floor, receive extra reward weight (not extra minted principal) up to 20%, or 25% if they hold the chain’s holder token above threshold.

4. Architecture

Five contracts and one math library, compiled once per chain against a ChainLib of constants.

System diagram

5. Networks and DEX hosts

One binary per chain. update-chain-lib.py selects the library, writes treasury / deployer / holder addresses, and rewrites the import. The constructor reverts if block.chainid does not match. PulseChain testnet and mainnet are Ethereum forks and retain the original Uniswap V3 factory and position-manager addresses; Pulse mainnet farming is configured against Liberty V3.

Fee tier is always 100 (0.01%). Pair tokens may have 6, 8, or 18 decimals. ZXO token is always 18.

6. Pool lifecycle

1. createPool deploys the token. If withoutPool is false, it registers the pool, packs caps, mints coreLP + coreStake to Zxo and v3StartAmnt to the deployer. If withoutPool is true, it only deploys a token — used to grind CREATE addresses until the token hex sorts below the pair so DEXScreener-class UIs render buys as buys. The live farm is a later call with withoutPool = false and forceLower = true.
2. Owner seeds satellite DEX pools via startV3pool. NFTs go to the burn address on a widened tick range.
3. finalizeToken sets isFinalized and burns any remainder. User staking cannot open until this is true.
4. initializePool(..., isCore=true) creates the canonical pool at the launch sqrt price if needed, requires slot0 to equal that price, and mints the single-sided core LP. Token id is packed into poolConfig.
5. initializePool(..., isCore=false) mints the narrower core-stake NFT, books it as owned by Zxo, increments stakes from 0 to 1. From that moment stake() is open.

Create and core-init are separate transactions (contract-size limit). A third party can initialize the factory pool at a wrong price and grief that pair; the team accepts that. A dead pair is abandoned and a new token/pool is opened.

7. User functions and flows

Everything a non-owner can call that changes state: stake, harvest, unstake, updatePool. Views: queryData, getUserData, getTargetAprsByIds, plus the public mappings.

7.1 Stake

stake(uint8 poolId, uint256 amount0Desired, uint256 amount1Desired,
      uint256 slippageBps, address referrer)

• Pool must exist and already have stakes > 0 (core stake is in).
• Caller may hold at most 21 positions across all pools.
• Slippage ≤ 5_000 bps (50%). Combined notional, normalized to 18 decimals, ≥ 1e6 wei-equivalent.
• Pool tick must sit strictly inside the user range (health gate).
• First referrer write wins. Zero becomes the treasury. Self or any other address is allowed and pays no treasury commission.
• Tokens are pulled, a V3 position is minted to Zxo on the user tick band, dust above the decimal-specific threshold is refunded, bonus weight is applied, the position is booked, auto-adjust may run.

7.2 Harvest

harvest(uint64 tokenId, uint8 poolId, Action_ action)

Action_ on this path is only Claim (0), CollectFees (1), or ClaimAndCollect (2). Health gate applies. You must own the position and it must still have liquidity.

• Claim mints pending ZxoToken. If a referrer is set and is not you, they receive refRateBps of pending and you receive the rest. Total minted equals pending — the referral is a split, not extra inflation.
• CollectFees calls V3 collect on your NFT and forwards both tokens to you.

Rewards keep accruing while the pool is out of range. The gate only blocks when you can take them. Unstake does not require the gate.

7.3 Unstake

unstake(uint64 tokenId, uint8 poolId, bool acceptForfeit, address to)

• One-day lock from stakeTime.
• Pending is never paid here. Harvest first, or pass acceptForfeit = true. If false, pending must be ≤ 1e12 (dust).
• to = address(0) means you. to = Zxo is rejected. A contract recipient must implement onERC721Received.
• Weight and TVL come off the pool, the storage row is deleted, the NFT is safeTransferFrom last.

7.4 Public poke

updatePool(poolId, updateAll) accrues and, if the one-hour cooldown has passed, retargets rewardRate. Anyone may call it.

User journey

8. Owner capabilities

Owner is trusted for bootstrap and for policy inside the packed caps. Owner is not trusted with user principal. After every planned pool is live, ownership of Zxo may be renounced; users keep stake / harvest / unstake.

9. Formulas

Amounts of the non-18-decimal pair token are scaled to 18 decimals before any ratio or TVL math: ×$10^{12}$ for 6 decimals, ×$10^{10}$ for 8.

9.1 Accrual (MasterChef)

Each pool stores an accumulator and a per-position debt. Time is wall-clock seconds. $R$ is rewardRate in token wei per second. $S$ is totalStaked (V3 liquidity plus bonus weight). Precision $P = 10^{18}$.

where $L$ is the position’s booked liquidity (base V3 liquidity plus any stake bonus) and $D$ is rewardDebt, set to $L \cdot \mathrm{acc} / P$ at stake and after every claim. If $S = 0$ the accumulator is frozen and lastRewardTime is stamped to now.

9.2 Auto-adjust of $R$

At most once per hour, using TVL $V =$ totalTokens (normalized notionals, not liquidity units) and target $A$ in bps:

clipped by two packed ceilings that cannot be raised:

maxNormalAPR itself cannot exceed 32 000 bps (320%). Default target at create is 1 000 bps (10%). Type-2 owner update may only lower $R$, not raise it; auto-adjust can raise $R$ back up to the clip.

Observed APR versus TVL, for dashboards:

Users earn below headline $A$ while the core stake holds a share of $S$ and never claims (accepted M-03). Auto-adjust does not close that gap; it shrinks as user TVL grows.

9.3 Stake bonus (reward weight, not extra tokens deposited)

Let $a$ be the normalized ZXO (local) side actually minted into the NFT and $b$ the normalized pair side. $T = a + b$. If either side is zero, or $b \le a$, bonus is 0. Otherwise:

Bonus starts only when the paired ratio clears 50%:

In code: bonusBps = (pairedRatio - 5e17) * 59538 / 1e18, then cap at 2 000. That constant reaches the 20% cap at a paired ratio of about 53.36% — roughly 20 ticks above parity. Then:

If the caller’s holder-token balance ≥ $3\,690\,000\,000 \times 10^{18}$:

so the max weight bonus is 25%. $B$ is added to booked liquidity. TVL (tokens) stays $T$. The bonus changes how emissions are split, not how many tokens the user deposited.

9.4 Referral split on claim

$r \in [300, 3000]$. If referrer is unset-as-self or equals the claimer, $\mathrm{ref} = 0$ and the user receives all of pending. Treasury earns only when the stored referrer is the treasury (the default for address(0)).

9.5 Slippage on mint

Users: $s \le 5000$. Owner init/seed: $s$ is a frontend parameter; $s = 10000$ is a zero minimum; $s > 10000$ reverts.

9.6 Health gate

Pool is healthy iff the current tick is strictly inside the user stake band:

18-dec band is $[-300, 300]$. 6-dec and 8-dec bands are the documented parity tick ± 300, flipped when ZXO is token0. Spot tick, not TWAP.

10. Tokenomics

There is no single protocol token. Each pool has its own ZxoToken, minted by that pool’s farm and burned by holders via ERC-20 burn. Utility is the farm reward and the inventory side of the V3 pair.

Address mining (withoutPool + forceLower) is how a pool gets ZXO as token0, so buy flow charts as buys on DEX screens.

11. Technical design

State

Events

One packed event: ZxoEvent(user, data0, data1, data2, Action_) with actions Claim, CollectFees, ClaimAndCollect, Bonus, Unstake, AutoAdjust, Stake, Referrer.

Access and reentrancy

Owner functions are onlyOwner. Every state-changing external on Zxo and the deployer is nonReentrant. Unstake performs the ERC-721 transfer last. ZxoToken disables transferOwnership and renounceOwnership with custom errors. Zxo itself can still renounce Ownable2Step — that ossifies admin, not users.

Upgradeability

None. No proxy. New behavior is a new pool or a new deploy. Caps cannot move up.

12. Security considerations

Pre-mainnet source review dated 26 September 2026. Classification: no principal-theft finding. A follow-up review will match creation transactions and deployed bytecode after launch.

Threat model — what is in scope

• Theft of another user’s NFT or the tokens inside it
• Owner sweep of user assets
• Mint outside the packed caps
• Permanent freeze of unstake

Protections

• NFT custody + owner check + no rescue function
• Unstake independent of health and of owner
• SafeERC20 + forceApprove for USDT-class pair tokens
• Chain-id constructor lock + ZxoVerify before Zxo is deployed
• Finalize-before-stake on the deployer
• Core-LP slot0 must equal launch price
• User slippage cap, 21-position cap, 255-pool cap, uint128/uint96/uint16 downcast guards

Accepted risks (team + review)

13. Gas efficiency

• Plain revert() on failure (smaller bytecode, cheaper revert data).
• One packed poolConfig word instead of five hot slots.
• One event signature for all user and adjust actions.
• Unchecked increments where values are bounded by caps and by the permanent core stake.
• Hardcoded tick and sqrt-price constants; no on-chain $\log$ / $\sqrt{}$.
• Dust below threshold is left in Zxo rather than refunded.
• Create+init were kept as two functions so Zxo stays under the 24 576-byte runtime limit.
• Optimizer 200 runs, via-IR off, EVM shanghai (PUSH0). Chains without Shanghai must compile to paris.

14. Interfaces and dependencies

• OpenZeppelin 5.x: IERC20, IERC20Metadata, SafeERC20, IERC721, IERC721Receiver, Ownable, Ownable2Step, ReentrancyGuard, ERC20, ERC20Burnable.
• Uniswap V3–compatible INonfungiblePositionManager: mint, collect, createAndInitializePoolIfNecessary.
• Factory: getPool, and for verify owner + feeAmountTickSpacing(100).
• Pool slot0() via raw staticcall, first two words only, so extra fork return fields do not break the health gate.
• ZxoToken must expose OZ burn(uint256) for deployer finalize.

15. Deployment

Addresses are not canonical until the post-launch matching audit. Process per chain:

1. Run update-chain-lib.py, compile with solc 0.8.36.
2. Deploy ZxoTreasury.
3. Deploy ZxoVerify(false). Require isVerified().
4. Deploy ZxoV3Deployer. Write its address into the lib.
5. Recompile verify + Zxo. Deploy ZxoVerify(true), then Zxo.
6. setZxoContract once.
7. Move treasury destination, wait 7 days, optionally lock. Move ownership to the production key. Record creation hashes for the second audit.

ZxoVerify will refuse a zero factory, NPM, holder, treasury, or (when asked) deployer, a factory without fee 100, or an NPM whose factory() pointer does not match.

16. Governance

No token vote, no Governor, no proxy admin. Policy knobs after launch are target APR (clipped), referral rate (banded), and lower-only reward rate. New pools require owner. When the protocol will not open more pools, Zxo ownership is renounced. Treasury destination is a separate, lockable sink. Production expectation: multisig or controlled key on Zxo and the deployer (2-step), careful single-step key on treasury.

17. License and compliance

The Licensed Work is under Business Source License 1.1, licensor Zxo, additional use grant none, change date 23 September 2029, after which it becomes GPL-7.0-or-later as specified in the header files. This whitepaper is a technical description, not an offer of securities and not legal advice. Pair-token listing and frontend geo-fencing are off-chain concerns.

18. Roadmap

1. Finish per-chain testnet farms (ChainLib + Verify + seed + finalize + core).
2. Mainnet deploy per chain with recorded creation hashes.
3. Post-launch audit matching source to bytecode and addresses.
4. Open user staking pool by pool once core walls are in.
5. Optional ownership renounce after the planned set of pools is live.

19. Appendix

Glossary

Tick sheet (user band and core)

Source map

• contracts/Zxo.sol
• contracts/libraries/ZxoLib.sol
• contracts/ZxoTreasury.sol
• contracts/ZxoV3Deployer.sol
• contracts/ZxoVerify.sol
• contracts/tokens/ZxoToken.sol
• Companion audit: Zxo-Security-Audit.html