TimbSwap Documentation

Overview

TimbSwap is a constant-product (Uniswap-V2-style) automated market maker paired with a set of on-chain incentive games. It is open-source, decentralized, permissionless, and non-custodial: the protocol is a set of Solidity smart contracts on Arbitrum — anyone can call them directly, no one can pause your funds, and you always hold your own keys. All state is read live from the chain — the frontend is static and hosts no backend. You interact by connecting an EVM wallet (MetaMask, Rabby, or a mobile in-app wallet) set to Arbitrum Sepolia.

The core surfaces are:

• Swap — trade tokens against AMM pools.
• V2 Pools — a read-only explorer of every pool, its reserves, TVL, and 24h volume.
• Farm — stake LP or TIMBS to earn TIMBS emissions.
• Lock Vault — time-lock any token and appear in the public registry.
• Compete — the Prize Scroll game, where swaps and nudges push a shared meter toward a payout.
• Governance — deposit TIMBS for voting power on proposals.
• Analytics — protocol metrics and settled round history.

Architecture — the incentive engine

The surfaces above are modules; the product is the loop that connects them. Value moves in one direction, on a fixed cadence:

1. Trade. Swaps pay a 0.3% fee — 0.25% to liquidity providers, 0.05% to the protocol treasury. Eligible swaps also advance the prize meter.
2. Collect. The treasury accumulates fee inflow; ticket deposits sit in a yield vault whose accrual grows the prize pot. All backing is visible on-chain.
3. Reward. Every six rounds an autonomous keeper sweeps what was collected and replenishes the reward pools — prize pot, farm, staking, then boosted farms — in that fixed priority order.
4. Return. Winners claim, stakers and farmers compound, players re-enter — feeding step one again.

The whole protocol is Solidity smart contracts (0.8.24), open-source and verified on Sourcify so anyone can read the exact deployed code. The layout mirrors the loop: the AMM core (Factory, Router, Pairs) generates fees; the game layer (TimbPrize, GameRegistry, YieldVault, PrizeEscrow) runs rounds and holds the pot's backing; the emissions layer (Staking, Farm, BoostFarm, Treasury) distributes rewards under the solvency rules described below. Settlement and payouts are permissionless — anyone can call them, no privileged operator required. The frontend is a static site — every number you see is read live from chain, and the keeper runs unattended.

Getting started

1. Add the network. Arbitrum Sepolia — chain ID 421614, RPC https://sepolia-rollup.arbitrum.io/rpc, explorer sepolia.arbiscan.io. Connecting your wallet on any TimbSwap page will offer to add/switch to it automatically.
2. Get testnet ETH. Use a public Arbitrum Sepolia faucet to fund gas. You need a small amount of Sepolia ETH for every transaction.
3. Connect. Click Connect Wallet in the top bar. Reads (quotes, balances, tables) always come from the public RPC; your wallet is only asked to sign transactions.
4. Get test tokens. Swap a little ETH for TIMBS or another listed token to start using the farm, lock, and compete surfaces.

Swapping

The Swap page trades an exact input for an estimated output (or the reverse). Prices come straight from a pool's reserves using the constant-product formula, minus a 0.3% pool fee that accrues to liquidity providers and a small protocol fee.

• ETH is wrapped automatically. ETH↔WETH is a 1:1 wrap/unwrap with no pool, fee, or slippage; ETH→token routes through the WETH pool.
• Slippage & min-out. Your minimum received is computed from the live quote and a slippage tolerance; if the pool moves against you past that, the swap reverts rather than filling at a bad price.
• Direct pairs only (today). A swap needs a direct pool between the two tokens. If none exists you'll see “No liquidity for this pair” — route through WETH as two swaps, or see the multi-hop routing plan on GitHub.
• Add to wallet. Where shown, a “＋” lets you register the output token in your wallet — always confirm the address first (see Verify authenticity).

Liquidity & V2 Pools

Add liquidity from the Swap page's Liquidity tab. You deposit both sides of a pair in the current ratio and receive LP tokens representing your share; you earn the 0.3% fee pro-rata and can withdraw anytime by burning LP.

The V2 Pools page is a wallet-free explorer showing every pool's reserves, USD TVL (for pools with a priceable side), 24h volume, recent trades, and recent liquidity events — all read live from chain.

Farm (staking)

The Farm lets you stake eligible tokens to earn TIMBS emissions. Rewards stream at a per-second rate and are claimable at any time; claiming does not reset your stake.

Reading APR. APR is derived from the reward rate and the total staked, so it swings when either changes. On a small testnet pool a tiny stake can produce an astronomical headline APR — the UI caps the displayed figure, and you should treat testnet APR as illustrative, not a yield promise.

Lock Vault

The Lock Vault time-locks any ERC-20 for a duration you choose. Locked tokens are held by the vault until the unlock time, then withdrawable by you. Active locks appear in the Public Lock Registry with a masked owner, a unique lock ID, and the amount.

A green TIMBS badge marks a lock holding the canonical TIMBS contract — it is an exact address match, not a symbol match, so it can't be spoofed by a look-alike token. Token symbols and decimals for other locks are read on-chain; always verify a token before trusting its label.

Compete — the Prize Scroll

The Compete page is an on-chain game. A shared meter (the “scroll”) advances as players nudge it; when a round settles, entrants split the pot.

• Nudging by swapping. An eligible swap advances the scroll by a set weight. Eligibility is checked on the input token — trading an eligible token forward feeds the meter and the fee/burn loop.
• Free nudges. You can also advance the scroll directly (gas only), capped per wallet per segment so no one can dominate the meter for free. Paid swap-nudges aren't capped because they cost fees.
• Entries & settlement. Each round records its entrants; when it settles, the entry count is snapshotted and winners are drawn. Past rounds on the Compete and Analytics pages show the entries recorded at the end of each round.
• One ticket per wallet per round, with a lineage so you can see and replace a pending entry.
• Two clocks. A winner claims within 2 rounds of the match (a lapsed prize recycles into the pot). Ticket principal stays withdrawable for 4 rounds after the later of the ticket's last eligible round and its claim window — so winning near the end never shortens your refund time (it can only extend it, up to LER+6).
• Locked characters are jittered — within their class. When a segment closes, the locked character is the nudge counter mixed with the settling block's hash, so the exact character can't be aimed. But the jitter stays in the same class as the live character: a letter locks to a letter (A–Z), a digit locks to a digit (0–9). So nudging lets you aim the class (letter vs number) for each position, while the precise character stays unpredictable.

The exact tuning (nudge weights, segment caps, emission balance) is documented in the repository's game-balance spec.

Governance

Governance lets you deposit TIMBS for voting power and vote on proposals. Your deposited TIMBS are locked while you hold active votes and are withdrawable afterward. A quorum is required for a proposal to pass.

Analytics

Analytics surfaces protocol-wide metrics and a paginated round-history table (with per-round entries, winners, and pot). Market top-line data is public; some protocol internals reveal once a wallet is connected.

TIMBS token

TIMBS is the protocol's native test token. New supply is minted only as emissions to the staking and farm pools (and by the owner), and is bounded by a hard cap. Emissions fund farm rewards; the reward rate is set by governance/owner actions, which is what moves farm APR over time.

Tokenomics & emissions

• Fixed supply. TIMBS is hard-capped at 100,000,000. There is no mechanism to mint beyond the cap.
• Fee split. Every swap's 0.3% fee splits 0.25% to LPs and 0.05% to the treasury, which funds buybacks and the reward cycle.
• The epoch waterfall. Every 6 rounds the keeper measures what was actually claimed from the farm and staking pools and what the treasury actually collected, then refills in priority order: the farm first (capped at 80% of its claims), staking next (up to 1.25× its claims, but no more than 80% of what remains), and boosted farms receive only the remainder. If inflow runs short, the tail of the waterfall goes unfunded — nothing is printed to cover the gap.
• Solvency stop. Reward contracts track every wallet's accrued-but-unclaimed balance as an explicit liability. When total obligations reach 99% of reserves, accrual halts until the next refill — the system cannot promise tokens it does not hold.
• Self-retargeting rates. Emission rates are recomputed from free (unowed) reserves over the emission window, so a shrinking reserve slows emissions instead of over-committing.

Risks

Plainly stated — these apply on testnet today and would apply with real value on mainnet:

• Smart-contract risk. The contracts are testnet-hardened but unaudited. An independent audit is a gating condition for any mainnet deployment. Permissionless refund and recovery paths exist so funds are not trapped behind an operator.
• Impermanent loss. Providing liquidity carries standard AMM impermanent-loss risk, larger on thin or volatile pairs (the boosted farms are the highest-risk seat).
• Game randomness. Locked characters are jittered with the settling block's hash. You can aim a position's class (letter vs digit) but not the exact character — treat the game as chance-weighted, not skill-guaranteed.
• Emissions variance. APR figures move with the epoch waterfall and total staked; a testnet APR is illustrative, never a promise of yield.
• Regulatory. Prize mechanics are classified differently by jurisdiction. On testnet nothing has monetary value; before any real-value launch, formal legal review (and likely geofencing) is a gating condition.
• Testnet impermanence. Test networks can be reset or halted at any time; assume all testnet state is disposable.

Verify authenticity

Network: Arbitrum Sepolia (chain ID 421614). Tap any address to open it on Arbiscan.

Privacy & data

TimbSwap's frontend is static and stores no accounts. What it touches:

• Your wallet. Connecting shares your public address with the site (standard for any dApp). The app reads balances and signs transactions you approve; it never has custody of your keys or funds.
• Public RPC. Reads go to a public Arbitrum Sepolia RPC endpoint, which sees the requests your browser makes (a normal property of using any public node).
• Local storage. Your theme choice and last-connected state are kept in your browser only.
• Diagnostics (DebugHub). The app can emit anonymous diagnostic checkpoints and error events to help debugging. This telemetry is about app behavior, not your identity, and no private keys or seed phrases are ever collected. If you export a debug log to share, review it before sending.

Disclaimer

TimbSwap is an experimental, unaudited testnet project provided “as is,” without warranties of any kind. Testnet assets have no monetary value and testnets can be reset or halted at any time. Interact at your own risk, verify every address, and never treat anything here as financial advice.