Skip to content
XosBridge

Overview

How XosBridge connects token markets

Every admitted token has its own Uniswap v4 pool against ETH. A hook on that pool takes a 1% community fee on every buy and sell, in ETH, and records which market it came from. Once a day, the fees each market sourced are allocated to holders of the other admitted markets, weighted by how long and how much they held. The allocation is published as a reproducible artifact plus a Merkle root; holders claim on chain. "Bridge" means the connection between communities. Nothing is transferred between chains.

Rewards depend on actual trading activity and eligibility. A new launch adds a potential source of fees, not guaranteed income. This software is unaudited and this version is not trustless.

Fee arithmetic

Three separate costs

CostRateBasisGoes to
Community fee100 bpsbuy: ETH sent · sell: ETH received (gross)FeeVault → other communities
LP fee3000 (0.30%)pool input after the community feethe locked liquidity position
Price impact + gasvariespool depth · networkthe pool · validators
  • Only exact-input swaps are supported; exact-output swaps revert in the hook.
  • Buy (ETH → token): fee = floor(amountIn × 100 / 10000) taken in beforeSwap from the specified currency. The pool swaps amountIn − fee. You pay exactly amountIn.
  • Sell (token → ETH): fee = floor(ethOut × 100 / 10000) taken in afterSwap from the unspecified currency. You receive ethOut − fee.
  • Rounding is always down, towards the trader. Buys under 100 wei pay no fee.
  • The fee is moved to the vault inside the same callback with PoolManager.take; the hook never holds funds and never swaps the fee into another asset.
  • No fee is collected while fewer than two markets are admitted, while collection is paused, or on a market that is not admitted. The market page shows this as "fee off".

Worked examples are replayed by contracts/test/unit/Hook.t.sol and documented in docs/FEES.md.

Reward specification (rules v1)

Daily epochs, fixed eligible set, time-weighted balances

  • Epoch n = [genesis + n·L, genesis + (n+1)·L) in block timestamps; L is 86 400 s on this network.
  • The eligible set is fixed at the boundary: markets admitted before the epoch starts and not removed before it. Admissions during an epoch count from the next one.
  • Fees from source A exclude A's holders and are split equally across the other eligible communities with non-zero weight; inside a community, by time-weighted balance derived from the complete transfer history (opening balance + every transfer, integer seconds).
  • A wallet holding several eligible tokens earns through each. Holding only A never earns from A.
  • Declared nonparticipating addresses (PoolManager, locker, launchpad, vault, distributor, hook, router, burn addresses, and any address the registry excludes) carry no weight.
  • No recipient with weight → the amount carries forward, still tagged with its source. Rounding dust carries forward the same way. Nothing is ever diverted to the team.
  • Epochs are computed strictly in order from finalized blocks only. A reorg deeper than the finality depth after publication is handled by invalidation before activation; after activation a root is immutable.

Full text with every edge case: docs/REWARDS.md. Executable form: src/protocol/epoch.ts, tests in src/protocol/__tests__.

Launch requirements

What a launch is and what it enforces

  • Standardized ERC-20: fixed supply minted once, no mint, no tax, no blacklist, no pause, no owner (XosToken.sol).
  • One transaction: token + pool initialization (LP fee 0.30%, tick spacing 60, ETH as currency0) + full-range liquidity into the LiquidityLocker + registry entry. It cannot half-complete.
  • Creator allocation ≤ 50%, sent to the creator and not locked. Liquidity lock ≥ 30 days or permanent, enforced by the locker; LP fees are collectable by the creator at any time.
  • Minimum initial liquidity: per network configuration.
  • Admission is a curated decision by the registry owner and requires the lock to still be active. It reduces abuse (mass token creation against equal per-community allocation) but does not eliminate manipulation.

Roles and trust

Who can do what

Registry owner (curator)admit / remove markets, declare exclusions, pause fee collection. Cannot touch funds, change the fee rate or mint.
Vault ownerforward collected fees to the distributor for an ACTIVE epoch, never above the published total. No other outflow exists.
Publisherpublish an epoch root. Cannot activate early, cannot move funds.
Distributor ownerinvalidate a published root before activation; set the publisher and the review delay. Cannot replace an active root or withdraw funded rewards.
Launchpad ownerpause new launches; set the minimum liquidity. Pausing launches does not affect trading or claims.
Market creatorcollect LP fees; withdraw liquidity after the unlock time (never, if permanent).
Anyonelaunch, trade, activate a published epoch after the delay, claim, verify an epoch.
Nobodychange the 1% fee, replace an active root, take user rewards, mint tokens, upgrade a contract (none are upgradeable).

On a public deployment the registry, vault, distributor and launchpad owners should be one multisig and the publisher a separate operational key. A published root proves the publisher committed to an allocation, not that it is fair; fairness is checked by reproduction during the review window.

Network status

Robinhood Chain (chain 4663)

Contracts

Address manifest

No XosBridge deployment is recorded for Robinhood Chain. The manifest contracts/deployments/4663.json is written only by a real broadcast of script/Deploy.s.sol.

Verify an epoch

Reproduce the allocation yourself

# with your own RPC + database (see README)
pnpm build:contracts
pnpm worker --once            # index to the current head
pnpm epoch:verify <epochId>   # recompute from indexed inputs, compare root + artifact hash on chain
# exit code 0 = reproduces byte for byte; 2 = mismatch (do not let it activate)

Artifacts are served at /api/epochs/<id>/artifact and committed on chain as keccak256(canonical JSON). See the rewards page for the review window of each epoch.