GesolvFi documentation

Network: Robinhood Chain (4663). Contracts are deployed on this network; addresses are on the status page.

Overview

GesolvFi is five modules around one settlement asset (USDG) and one vault:

• Orbit Vault — ERC-4626 shares over USDG; the counterparty of every index position.
• Global Index Perpetuals — isolated-margin synthetic exposure to 34 equity benchmarks, executed at the next oracle level.
• Sealed Order Crossing — WETH/USDG batch crossing with commit, reveal, settle and claim.
• Adaptive Liquidity Ladders — owner-controlled bid/ask rungs with a bounded operator.
• Launchpad — fixed-supply tokens on Uniswap v3 with locked liquidity and an on-chain fee split.

Every amount is an integer in base units on chain and in the app; formatting happens only at the edge. Nothing in the interface is a guarantee of returns, price or liquidity.

Orbit Vault

Shares have 18 decimals; the first depositor is protected by a virtual-offset of 10^(18 − asset decimals). Direct token transfers are ignored until the owner calls skim(), so a donation cannot move the share price.

Deposit, mint, withdraw and redeem follow ERC-4626 with previews; depositWithMinShares, mintWithMaxAssets, withdrawWithMaxShares and redeemWithMinAssets add user slippage bounds. An explicit exit fee (≤ 1 %) stays in the vault. Unrealized trader losses are not credited to NAV until realized; trader profits reduce every share. Liquidations that leave bad debt are absorbed by the vault. External yield strategies do not exist in this deployment.

Index perpetuals

Positions are synthetic exposure to a published index level, sized in USDG notional, isolated margin, one direction per market per trader. They are not stocks, ETFs or index licences; index names belong to their operators.

• Request → execute. Every open, increase, decrease and close is a request. Anyone (the keeper in practice) executes it at the first oracle level observed strictly after the request, while the session is open and the level is within maxStaleness. Market requests expire after 180 s; limit and stop requests carry a TTL up to 7 days. Escrowed margin is refunded on cancel or expiry.
• Fees. Taker fee on every notional change (split between vault and treasury). Funding accrues per second from skew: longs pay when long OI exceeds short OI, up to maxFundingRatePerDay; it stops while the session is closed.
• Risk. Leverage ≤ maxLeverageX (hard cap 25×, 10× by default), maintenance margin, position cap, per-side open-interest cap, backing capacity (utilization cap of the vault). Profit per position is capped at maxPayoutBps of notional and reserved in the vault when the position opens.
• Liquidation. Permissionless when equity falls below maintenance at a fresh open-session level. The liquidator receives liquidationFeeBps of notional from the remaining margin; anything left returns to the trader; losses beyond margin are bad debt for the vault.
• Closed sessions and outages. No execution, liquidation, margin removal or funding accrual while the session is closed. Positions are marked at the last close for up to 5 days; beyond that, or while the oracle breaker is active, the market cannot be valued and the vault holds deposits and withdrawals. A missing level is never replaced by a fabricated one.

Index oracle

Index levels reach the chain through a signed publisher. The worker reads levels from the data provider (Twelve Data), signs an EIP-712 Update with the publisher key, and relays it with the keeper key. The contract enforces authorship (PUBLISHER_ROLE), domain separation (chain id + contract + market id), replay protection (strictly increasing sequence, non-decreasing observedAt), clock sanity (publishedAt ≥ observedAt, ≤ 300 s ahead), freshness at submission (maxAge), plausibility bounds and a circuit breaker: a move larger than maxStepBps is parked until a guardian confirms it as signed or dismisses it. The publisher also signs the provider's session flag; the engine uses it to decide what “stale” means.

Historical charts come from the provider and are labelled with their source and timestamp; the local chain uses a clearly labelled fixture publisher. Without a provider key no level is published and no market can be enabled.

Sealed crossing

1. Commit — hash of (chain id, contract, batch, trader, side, quantity, limit, nonce, salt) plus escrow: USDG for buys (≥ qty × limit × (1 + fee)), WETH for sells (≥ qty). Cancellable until the commit phase ends.
2. Reveal — the sealed fields are disclosed; the contract checks the hash and the escrow.
3. Settle — after the reveal phase, inside the settle window, at the Chainlink ETH/USD ÷ USDG/USD level of the settling block (both feeds fresh, USDG inside its band). Eligible buys (limit ≥ P) and sells (limit ≤ P) cross pro rata with floor rounding; buyers pay ceilings, sellers receive floors; the crossing fee and rounding dust accrue to the treasury.
4. Claim — fill, proceeds and the unused escrow. Unrevealed orders are refunded in full. If the feeds are stale, USDG leaves its band or the window is missed, the batch aborts and every escrow is refundable.

Sealing hides quantity and limit until reveal. The escrowed asset reveals the side and an upper bound on size (over-escrow hides the exact size). Wallets and settlements are ordinary transactions: nothing is anonymous. Order secrets live in the browser; export them after committing and import them on another device to reveal or claim.

Liquidity ladders

A ladder is a user-owned contract quoting levels asks above and bids below a centre. Rung price = centre × (1 ± spacing × rung). Takers fill rungs and pay the owner's fee; fills are refused when a rung deviates more than maxDeviationBps from the Chainlink reference or when the reference is stale. Owners deposit, withdraw (any time, rungs are clipped), claim fees, pause, cancel and set parameters within on-chain bounds. An operator may only re-centre within maxRecenterBps of the reference after a cooldown, and set spacing inside the owner's bounds; revocation is immediate. No arbitrary calls, swaps or transfers exist for operators.

Launchpad

One transaction deploys a fixed-supply ERC-20 (no mint, no owner, no tax, no blocklist; holders may burn their own tokens), creates and initialises a Uniswap v3 pool against an allow-listed quote asset, mints a full-range position to the factory and sends the creator's share of the supply. The position NFT is the liquidity lock: principal can leave only after unlockAt, never for a permanent lock. Fee collection is permissionless; collected fees split on chain into the creator's claimable balance and the route's share at the percentages fixed and validated at launch.

Routes. Buyback & burn is live: quote fees are swapped into the token on its own pool at ≥ 30-minute TWAP − 3 %, at most 1 % of the pool's quote per execution, with a 10-minute cooldown, and burnt; token-side fees are burnt on arrival. AI compute funding and NFT acquisition are shown as unavailable with their prerequisites; they cannot be selected until a real execution path exists.

Transactions

Every write follows one lifecycle: simulate → awaiting wallet approval → submitted → confirming → confirmed, or reverted / cancelled / replaced. Success is shown only after the receipt has the required confirmations. Approvals are for the exact amount and only where needed. Disabled actions carry the reason (wrong network, no deployment, closed session, stale level, insufficient balance, caps). Pending hashes are stored per tab so a reload resumes watching the receipt; explorer links are shown wherever the network has an explorer.

Operations

The worker (pnpm worker) is a long-running process separate from the web app: indexer (checkpointed, reorg-safe, idempotent, backfilling), publisher (signs levels, records coverage), keeper (executes requests, clears expired ones, liquidates, pokes funding, opens/settles/aborts crossing batches, collects launch fees, executes buybacks, re-centres ladders that named it) and a heartbeat. Jobs are idempotent by key with exponential backoff; transactions are bounded by KEEPER_MAX_FEE_GWEI and re-sent with bumped fees when stuck. Keys: the publisher key only signs; the keeper and operator keys only pay gas. See docs/OPERATIONS.md in the repository for the runbook, market listing and deployment steps.

Trust assumptions

• The contracts have not been audited. They use OpenZeppelin 5.4 building blocks and are covered by unit, fuzz and invariant tests, but a test suite is not an audit.
• Index levels are as good as the publisher and its provider. The chain verifies signatures, ordering, freshness and plausibility — not truth. The guardian can halt a feed or confirm a parked level.
• The protocol admin can list and configure markets, pause new exposure, set fees within caps, pause deposits and place an emergency hold on withdrawals. The vault's engine is fixed at deployment.
• Chainlink feeds on this network have a 24-hour heartbeat and a 0.5 % deviation trigger: a settlement price can be hours old while it stays inside the band.
• Uniswap v3 contracts and the settlement/base assets are third-party contracts; USDG and WETH are upgradeable by their issuers.
• A market may be enabled only after provider coverage is verified; the free provider plan cannot sustain continuous coverage for 34 markets.

Status & addresses

Deployed addresses, live feed reads, worker heartbeat, market coverage, admin roles and operational limits are on the status page. The repository's docs/ folder holds the architecture, deployment, operations, trust and completion documents.