Skip to content
SvahFi

Documentation

Product documentation for SvahFi. The README in the repository covers the same ground for operators.

Overview

SvahFi is an asset discovery and liquidity interface for Robinhood Chain. It connects asset information to practical decisions: what an asset is, which contract and issuer it belongs to, what backing evidence exists and how recent it is, where it can be swapped and at what cost, and what a wallet holds. SvahFi is an interface and integration layer: it does not issue securities, audit reserves, guarantee redemption or returns, and it has no partnership with Robinhood.

Application routes

  • / — Landing page.
  • /app — Application overview and integration status.
  • /app/assets — Asset explorer: search, filters, wallet balances, contract inspection.
  • /app/assets/[address] — Asset detail: identity, price, issuer, backing inspector, liquidity pools, actions.
  • /app/swap — Route comparison, approval flow, transaction review and receipt tracking.
  • /app/portfolio — Balances, explorer-indexed holdings, history; address-only viewing.
  • /transparency — Sources, methodology, freshness thresholds, integration status.
  • /docs — This page.

Data states

Every value carries one of these states: live (read now, with block or timestamp), cached (last successful read, with its time), data unavailable (the read failed; shown as such), integration not configured (missing configuration, explained), unsupported asset, unsupported network, illustrative preview (labelled layout or registry preview, never live statistics), local development fixture (none ship in production). Failed live requests are never replaced with realistic-looking values.

Assets and registry

The registry (src/data/registry.ts) is curated: ETH, WETH, USDG and a set of Robinhood Stock Tokens, each with contract address, decimals, category, issuer, ISIN (Stock Tokens), price feed and source list with retrieval dates. Metadata is re-read from the chain on every view and mismatches are flagged. Any other address can be inspected: SvahFi validates the address, checks for contract code, reads name/symbol/decimals/totalSupply with per-call failure handling, and marks the contract unreviewed. Issuer identity is never inferred from a token name.

Backing information

Backing sources (src/data/backing-sources.ts) record provenance: issuer, document title and type, original URL, publication date if stated, reporting period if provided, SvahFi retrieval time, the document's own statement, and limitations. Sources are classed as onchain, issuer-reported, independent third-party attestation, or SvahFi-curated. Statuses: source available, publication date unknown, past configured freshness threshold, no source configured, source unavailable. Live checks include the WETH reserve read, the Stock Token beacon and terms() reads, the issuer registry lookup and an availability probe of each document URL. None of this produces a "verified backing" badge.

Swaps and approvals

Two adapters implement the SwapAdapter interface: the KyberSwap aggregator (documented /routes and /route/build endpoints, router pinned to the verified MetaAggregationRouterV2) and direct Uniswap v3 pools (official QuoterV2 and SwapRouter02). Quotes are bound to account, network, tokens, amount and slippage, and expire after 45 seconds.

  1. Fetch quotes from every configured route and compare output, minimum received, fees, route and quote age.
  2. Check the allowance for the selected router.
  3. If needed, approve exactly the input amount (the default and only option) and wait for the receipt.
  4. Build the transaction server-side; the guard decodes the calldata and compares destination, tokens, amount, minimum, receiver, fee lines, flags and permits with the quote. The browser repeats the check.
  5. Review the transaction: destination, native value, output, minimum received, fees, route, expiry.
  6. Confirm in the wallet, track the receipt, and open it on the explorer.

Rejected signatures, insufficient balances, wrong network, expired quotes, RPC failures, failed approvals, reverted transactions, account or chain changes and slippage reverts each produce a specific message. When no route is configured the page shows "Integration not configured" and keeps read-only features. A successful swap is never simulated.

Portfolio

Balances for the native asset and every registry ERC-20 are read in one pass with the Chainlink prices, valued with exact integer arithmetic. The aggregate is labelled "Known priced value" and the number of unpriced assets is stated; missing prices are never zero. Other holdings come from the explorer index and are labelled unreviewed. History is read from the explorer and, separately, from transactions initiated through SvahFi in this browser. Address-only viewing is labelled "Viewing address" with signing disabled. No protocol position adapters and no P&L exist in this version.

Network configuration

Networks are defined in src/config/networks.ts with values verified against the official documentation: Robinhood Chain (chain 4663) and Robinhood Chain Testnet (chain 46630), ETH as the native currency, official RPC and explorer URLs. The wallet receives the official public RPCs; the app reads through its own relay at /api/rpc, which forwards read-only methods only. This deployment serves Robinhood Chain. See the transparency page for the live probe.

Official references: Robinhood Chain — Connecting (opens in a new tab), Contracts (opens in a new tab), Stock Tokens (opens in a new tab).

Environment

Copy .env.example to .env.local. No value is a secret except a provider RPC URL with a key, which is server-side only.

NEXT_PUBLIC_SITE_URL
Absolute site URL for metadata and share images.
NEXT_PUBLIC_NETWORK
"mainnet" (4663) or "testnet" (46630). One network per deployment; never switched silently.
NEXT_PUBLIC_X_URL
Optional X profile URL for the footer. Unset means no social link.
ROBINHOOD_RPC_URL
Server-side mainnet JSON-RPC. Default: a key-free public endpoint. Provider keys live here only.
ROBINHOOD_TESTNET_RPC_URL
Server-side testnet JSON-RPC.
BLOCKSCOUT_API_URL
Explorer JSON API base (default: official host).
ISSUER_API_URL
Stock Token issuer API base (default api.robinhood.com/rhj).
KYBERSWAP_API_URL
Aggregator API base; "off" disables the swap integration.
KYBERSWAP_CLIENT_ID
Integrator id sent as x-client-id (cosmetic).
GECKOTERMINAL_API_URL
Pool liquidity provider base.
UPSTREAM_DOH_RESOLVE
Development only: resolve upstream hosts through DNS-over-HTTPS on DNS-filtered networks.

Development and deployment

pnpm install          # install (lockfile included)
pnpm dev              # http://127.0.0.1:27700
pnpm typecheck        # tsc --noEmit
pnpm lint             # eslint (Next + React Compiler rules)
pnpm test             # vitest (amounts, addresses, guard, freshness, portfolio…)
pnpm build            # production build
pnpm start            # http://127.0.0.1:27710
pnpm brand            # regenerate brand assets from the supplied logo
pnpm verify:network   # probe RPC, explorer, feeds and routers

Deployment: any Node 22+ host that runs Next.js; vercel.json is included. Set NEXT_PUBLIC_SITE_URL and, optionally, a provider RPC URL. A successful build is not a production-readiness claim: run the checks and the browser verification described in the README.

Adding assets and updating backing sources

  1. Verify the contract address against an official source (network docs, issuer registry) and the explorer; for Stock Tokens confirm the beacon slot.
  2. Add the entry to src/data/registry.ts with decimals, category, issuer, sources (label, URL, kind, retrievedAt) and verifiedAt.
  3. Add the Chainlink feed only if it appears in the reference-data directory for this network; read description() to confirm the pair.
  4. Add backing sources to src/data/backing-sources.ts with the publisher's own statement, dates known, retrieval time and limitations; link the ids from the asset.
  5. Run pnpm verify:network and pnpm test, then review the asset page.

Limitations and preview versus live

  • Live: contract reads, Chainlink prices, balances, swap quotes and execution (mainnet, with a wallet), issuer registry, explorer history, pool snapshots.
  • Preview: the landing page's asset table and portfolio card are layouts built from registry metadata, labelled "Illustrative preview"; they show no live statistics.
  • Not available: liquidity deposits, protocol positions, price history, P&L, testnet execution.
  • External providers rate-limit; a refusal degrades to a labelled cached read or an unavailable state.