OmniFi SDK

A TypeScript SDK for the OmniFi multichain RWA tranche protocol. It reads the on-chain ledger through per-screen methods and runs deposit, redeem, and receive as single calls. Every failure is a typed error that carries a display-ready message.

What is an OmniFi tranche product

An RWA (real-world-asset) product that accepts investors into a single managed pool split into two layers (tranches).

Investors deposit the asset (USDC) and receive shares. Share prices are finalized at each periodic settlement, and deposits and redemptions execute at that price. This is the same model as fund NAV pricing.

The multichain layout

• Spoke (Sepolia) — where user transactions run: deposit/redeem requests and receiving.
• Hub (Bifrost) — the source of truth for product configuration, settlement results, and the request ledger. Most reads come from here.

Requested funds travel to the hub over a bridge, get recorded, and settlement results propagate back to the spoke. A delay between request and receivable is normal — the SDK exposes the in-between progress as a timeline.

Product line-up — deposit vs basket

Four scenarios are live on the testbed. A·B·C are deposit-type (assets earn yield in sources); D is basket-type (ETF-like — a QQQ-mirroring mock-stock basket, inspect with basketHoldings()).

The single-chain TrancheSDK ships the same screen-data methods — priceHistory()·realizedApy()·profitHistory()·faucet() — and investmentRequests() enriches each request with its tx hash from the hub TxRegistry.

Quick Start

The minimal path from install to a first deposit request.

1. Install

pnpm add @omnifi/sdk        # peer: viem

2. Create the SDK

import { OmniFi, OmniFiError } from '@omnifi/sdk'

const omnifi = await OmniFi.create()   // auto-discovers the latest product (scenario A · USDC)

// only when targeting a specific product — everything else has sane defaults
const custom = await OmniFi.create({ productId: 0x0000000200000009 })

Vaults, assets and RPCs all have defaults — this is enough. Addresses are auto-discovered from the hub precompiles. Other options (defaultChainId · chains · locale · hubRpcUrl) only when you need them. All read methods work without a wallet.

3. First read — product info

const ov = await omnifi.overview()
console.log(ov.tvl?.formatted, ov.assetSymbol)          // "1,399.97" "USDC" (null before first settlement)
console.log(ov.tranches[0].aprPercent)                  // 3  (Senior fixed APR %)

4. Connect a wallet — actions only

omnifi.connect(window.ethereum)   // with wagmi: pass connector.getProvider()

5. First deposit

try {
  const { txHash, requestId } = await omnifi.deposit('senior', '100.5')
  // whitelist check, chain switch, approve, request, receipt — all done
} catch (e) {
  if (e instanceof OmniFiError) toast(e.userMessage)
}

6. Afterwards — poll for state

Once requested, the system proceeds automatically. Poll myAccount() every 10–15 s; the state moves processing → receivable, then call receive() to finish.

Core concepts

The rules that recur across the SDK. Everything else is reference lookup.

① Amount — the shape of every value

interface Amount {
  raw: bigint
  decimals: number
  symbol: string
  formatted: string  // '1,399.97' — floored, thousand-separated, display-ready
}

Render `${a.formatted} ${a.symbol}`; input is a decimal string. Neither side touches bigint.

② The error model

Every failure is an OmniFiError. Branch on e.code, display e.userMessage. The original error lives in e.cause — debugging only. Full table: Error Handling.

③ Lifecycle — users act exactly twice

Legend: user action automatic

Settlement runs on a schedule (60-minute cycles; orders close 20 minutes before cycle end). Late requests roll to the next round — overview().nextSettlementAt is the authoritative ETA.

④ Prices are settlement-finalized

Prices and TVL are values finalized at the latest settlement — not live quotes. Always show settledAt, and prefix estimate* results with "estimated".

Process stages & terminology

What stages a deposit or redemption goes through from request to receive, what each stage is called, and which SDK field surfaces it.

Deposit stages ↔ SDK

Mapping: deposit() returns txHash/requestId → activity() carries the bridging/supply timeline with per-step txHash (detail view only) → status 'processing' displays as "awaiting settlement" with nextSettlementAt → 'receivable' + confirmed amount → receive(). Redeem is symmetric; its payout wording defaults to estimated payout (pricing-mode dependent).

Five rules that shape screens

• No cancellation — cross-chain cancel is unsupported for both flows; say so in the confirmation modal. The SDK has no cancel API.
• One outstanding request per tranche × direction — disable the request button whenever status !== 'none'.
• Share tokens mint at receive time — display balance as wallet shares + receivable shares.
• Pending amounts earn nothing yet — mark them "not yet deployed".
• Qualify unconfirmed numbers as "estimated" — applies to all estimate*() output.

On-chain step reference (precompile enums)

The uint8 code and enum name the TxRegistry precompile assigns to each step. The SDK surfaces both the Korean label (TimelineStep.label) and the enum name (TimelineStep.labelEn); the enum name is the canonical id for cross-team communication (e.g. "CollectBridgeExecuted rolled back").

RequestStep

SettlementStep

WhitelistStep

Avoid these terms

overview() — product page in one call

Everything a product page needs: tranche structure, rates, prices, TVL, settlement schedule.

No parameters · no wallet required · throws OmniFiError on failure

Return fields — full Overview

ChainInfo — chains[] item fields

TrancheOverview — tranches[] item fields

Overview — remaining fields

Example result — live testbed

{
  productId: 8589934601,            // 0x0000000200000009 (scenario A) — shown as seq #9 in UI
  assetSymbol: 'USDC',
  depositChains: [49088, 11155111],
  chains: [{ chainId: 49088, label: 'Bifrost', nativeCurrency: 'BFC' },
           { chainId: 11155111, label: 'Sepolia', nativeCurrency: 'ETH' }],
  tranches: [                        // (tranche × vault chain) — 4 entries, first 2 shown
    { name: 'senior', chainId: 49088,    aprPercent: 3,    sharePrice: 1.000069, shareSymbol: 'oSR' },
    { name: 'junior', chainId: 49088,    aprPercent: null, sharePrice: 1.000335, shareSymbol: 'oJR' }, /* … Sepolia 2 */ ],
  tvl: { formatted: '2,300.25', symbol: 'USDC', raw: 2300254000n, decimals: 6 },
  settlementRound: 14,
  settledAt:        2026-08-21T03:52:45Z,  // render this next to prices
  nextSettlementAt: 2026-08-25T03:44:38Z,
  orderCloseAt:     2026-08-25T03:24:38Z   // for the cutoff countdown
}

myAccount() — user dashboard in one call

Balance, eligibility, per-tranche holdings and progress. Works with just an address.

Return fields — full MyAccount

ActionState field spec

ActionState — status and stage

Progress comes in two forms: a coarse request status and a detailed process stage. Drive the main widget from the request status only, and keep the process stage to detail views. Using both in one view makes the displayed state inconsistent.

steps[] carries the full sequence with state: 'done' | 'current' | 'upcoming' per entry — feed it straight into a progress bar. amount is the requested amount while processing and the receivable amount once receivable.

Example result

{
  canInvest: true,                   // false → show onboarding instead of the deposit button
  walletBalances: [
    { chainId: 49088,    balance: { formatted: '0',     symbol: 'USDC' } },
    { chainId: 11155111, balance: { formatted: '9,600', symbol: 'USDC' } } ],
  tranches: [                        // (tranche × chain) — same index as overview().tranches
    { name: 'senior', chainId: 49088,
      shares: { formatted: '0', symbol: 'oSR' },
      deposit: { status: 'none', statusLabel: null, steps: [], amount: null },
      redeem:  { status: 'none' } }, /* … 3 more */ ]
}

activity() — cross-chain progress timeline

Data for rendering where each in-flight request currently is, as a step timeline.

Empty array = nothing in flight (normal). Completed requests drop off automatically.

Example shape

[{
  requestId: '0x000000020000000200…',  // show the seq suffix in the UI, not the full id
  kind: 'deposit', tranche: 'senior', chainId: 11155111,
  amount: { formatted: '100', symbol: 'USDC' },
  phase: 'supplying funds',
  steps: [
    { label: 'requested',  done: true,  txHash: '0xce87d8…', chainId: 11155111, at: 2026-08-19T02:00Z },
    { label: 'bridging',   done: true,  txHash: '0x9a3e39…', chainId: 11155111, at: 2026-08-19T02:01Z },
    { label: 'at hub',     done: false, txHash: null, chainId: null, at: null } ],
  adapterLegs: [{ chainId: 49088, steps: [ /* yield-source legs */ ] }],
  settlementRound: null                // before a round is assigned
}]
// ※ steps/tx come from TxRegistry (txRecorder attestation) — may be empty where the recorder has not attested

priceHistory() — chart data

Per-round finalized prices and TVL, all plain numbers.

Example result — live testbed

[ …,
  { round: 8, at: 2026-08-19T15:02Z, senior: 1.000088, junior: 1.000000, tvl: 350.01 },
  { round: 9, at: 2026-08-20T03:33Z, senior: 1.000131, junior: 1.000000, tvl: 350.03 } ]
// all number — feed straight to a chart. senior rising = fixed APR accruing; junior flat = yield source idle

investmentHistory() — user deposit/redeem history

Powers the "my transactions" screen — derived entirely from on-chain reads, no indexer.

Newest first. Each entry: kind (deposit/redeem), tranche, amount (requested — asset for deposits, shares for redeems), received (confirmed — shares for deposits, asset for redeems; null while pending), round/at (settlement round and its ledger time), status.

Example result — live testbed

[
  { kind: 'deposit', tranche: 'senior', status: 'pending',   // just requested — awaiting settlement
    amount: { formatted: '100', symbol: 'USDC' }, received: null, round: null, at: null },
  { kind: 'redeem',  tranche: 'senior', status: 'approved',
    amount:   { formatted: '199.9908', symbol: 'oSR' },
    received: { formatted: '200.0005', symbol: 'USDC' },     // principal 200 + yield
    round: 6, at: 2026-08-19T03:27Z },
  { kind: 'deposit', tranche: 'senior', status: 'approved',
    amount:   { formatted: '100', symbol: 'USDC' },
    received: { formatted: '99.9952', symbol: 'oSR' },        // minted at settled price 1.000048
    round: 5, at: 2026-08-19T03:10Z } ]

profitHistory() — periodic P&L (day · week · month)

Powers the "my profit report" screen — profit vs principal per period, from on-chain reads only.

Accrues per-round held shares × settled-price change into period buckets — holdings are reconstructed from investmentHistory(). Each point: period label, profit (base asset), returnPct (vs period-start value; null when starting from zero), startValue/endValue, byTranche breakdown. P&L is realized (settled prices only).

Example result — live testbed

[{
  period: '2026-08',
  from: 2026-08-18T13:19Z, to: 2026-08-20T03:33Z,
  profit: { formatted: '0.0005', symbol: 'USDC' },  // senior yield on 200 USDC held for a few hours
  returnPct: null,                                    // zero holding at period start → mark as "new entry"
  startValue: { formatted: '0' }, endValue: { formatted: '0' },  // fully redeemed within the period → ends at 0
  byTranche: { senior: 0.000598, junior: 0 }
}]

allocation() — portfolio composition

How the product allocates capital across chains and yield sources — for composition charts.

chains[] — per-chain weight (weightPercent) with nested per-source weights (onchain/offchain). valuations/round — latest settled valuation snapshot (see sourceValuations()); null before the first record.

basketHoldings() — basket constituents

Constituents, current prices, values and target weights for basket-type (ETF-like) products. Scenario D (Robinhood QQQ-mirroring basket) only — deposit-type products (A·B·C) return an empty array.

const holdings = await omnifi.basketHoldings(46630)
// [{ symbol: 'mNVDA', amount: 0.8098, priceUsd: 219.91, valueUsd: 178.09, weightPercent: 20.2 }, … 8 entries]

Custom flow reads — reward claims etc.

Timelines for governance-registered custom flows (e.g. reward-pool claims). Same surface for single-chain and multichain products; every read hits the hub CustomFlows(0x…0204) precompile.

Reward-specific helpers (rewardClaims() etc.) live on the Rewards page — this page covers the generic flow reads only.

flowId is a bytes16 slug — use the FLOW_IDS constants (currently FLOW_IDS.rewardClaim). Absence is signalled by sentinels, never reverts (unlike TxRegistry's get_request): unregistered descriptor → null, missing instance → null, empty history → empty array. recorded_at is a hub block number, not a timestamp — sort with it, but resolve display times via tx_hash on the source chain.

Rewards — balance, claim, history

Bonus yield for products with the RewardPool add-on (currently scenario B). The reward asset can differ from the deposit asset — B deposits JPYC and rewards USDC.

Rewards accrue only while holding shares across harvest ticks. On-chain claimable is lazily synced — the SDK adds the pending portion (lane delta × share value). profitHistory() attaches per-period claimed rewards as a separate rewards field (different currency — never summed into profit).

Yield sources — which protocol, how much

Which yield protocols the product is deploying into right now, per-adapter. Each adapter's name(), current value, and allocation in one call.

const sources = await sdk.yieldSources()
// [{ address, chainId, name, asset, assetSymbol, totalAssets, targetWeightBps, allocationPct }]

Enumeration: single-chain reads the product Valuation's adapter list + targetWeights; multichain reads the latest settlement's get_adapter_valuations (per-adapter principal).

sourceValuations() — yield-source valuations

Per-round adapter valuation detail — deployed principal, USD value, asset positions.

Each entry: chainId/adapter, principal (base asset), totalUsd (NAV-counted sum), positions[] (per-asset amount, USD price, counted — false for pre-swap reward tokens). Defaults to the latest round; null when not recorded.

whitelistStatus() — eligibility & propagation

Per-vault canonical registration and the latest grant/revoke propagation — for onboarding and ops screens.

Return fields — WhitelistState

VaultWhitelist — vaults[] item fields

WhitelistAction — action fields

settlementStatus() — per-round cross-chain record

One round number → the full processing record: trigger tx, per-chain steps (NAV collect → finalize), and the complete bridge-attempt history (successes and rollbacks).

Safe for any round — untriggered rounds return status 'Queued' without reverting. Fields: status/statusLabel (badge), trigger, chains[].steps (per-step tx/time/failed), progress, bridges[].legs[].attempts (ordered success/rollback history — the failures the steps array hides). Rounds with no approved requests have no finalize step at all (nothing to distribute — absent, not failed). Price/NAV series per round live in priceHistory(); poll only Triggered rounds — settled ones are immutable.

Estimates — estimateDeposit / estimateRedeem

Live "you will receive ≈" hints while typing, based on the latest settled price.

Returns

• Prefix with "est. ≈" — final amounts are fixed at settlement.
• Debounce input (~250 ms).

deposit() — request a deposit

One call runs validation through receipt confirmation, returning a requestId that joins the timeline.

1. Wallet connected → NOT_CONNECTED
2. Parse amount → INVALID_AMOUNT
3. Balance check → INSUFFICIENT_BALANCE
4. Whitelist check → NOT_WHITELISTED
5. Auto-switch to the spoke chain (Sepolia)
6. Approve first if needed (waits for confirmation)
7. Send request tx → wait for receipt → extract requestId

At most two wallet signatures; one if already approved.

Returns

redeem() — request a redemption

Redeems held shares for the asset. Same flow as deposit, two differences.

• Quantity is in shares — for "redeem all", feed formatUnits(shares.raw, decimals) back in.
• No whitelist check — holding shares implies eligibility.

Returns

receive() — claim finalized funds

Brings finalized shares (deposits) or assets (redemptions) into the wallet. The final user action.

• Call only when receivable; otherwise NOTHING_TO_RECEIVE is thrown (safe).
• Receives the full finalized balance at once — no partial claims.
• Runs on the spoke chain — auto-switched, one signature.

Returns

faucet() — test funds testnet-only

Claims the deposit asset from the per-chain UniversalFaucet — a transfer from a pre-funded balance, not a mint.

// multichain — several deposit chains, so pass chainId (wallet switches, then claims)
const txHash = await omnifi.faucet(11155111)          // 1,000 (default)
await omnifi.faucet(49088, 500_000000n)               // explicit raw amount

// single-chain — claims the product chain's deposit asset
await sdk.faucet()

UI Recipes

How the four common screens compose from SDK calls — the same patterns used by the partner app.

① Invest widget — branch on ActionState

const action = tab === 'deposit' ? tranche.deposit : tranche.redeem

const label =
  action.status === 'receivable' ? `Receive ${action.amount.formatted} ${action.amount.symbol}`
  : action.status === 'processing' ? action.statusLabel   // request-status axis drives the CTA
  : tab === 'deposit' ? 'Deposit' : 'Redeem'

② Progress timeline card

{(await omnifi.activity(user)).map((a) => (
  <Card key={a.requestId}>
    <Row>{a.tranche} {a.kind} · {a.amount.formatted} — <Badge>{a.phase}</Badge></Row>
    <Chips>{a.steps.map((s) => <Chip done={s.done}>{s.label}</Chip>)}</Chips>
  </Card>
))}

③ Product header — with the reference time

<Stat label="TVL (as settled)" value={ov.tvl ? `${ov.tvl.formatted} ${ov.assetSymbol}` : 'No record'} />
<p>{ov.settledAt && `as of settlement #${ov.settlementRound}, ${fmt(ov.settledAt)}`}</p>

Error handling — eleven codes and their UI responses

Everything a catch block needs.

Polling strategy

Polling beats event subscriptions on simplicity here — and the SDK batches calls internally (multicall on the spoke, JSON-RPC batching on the hub), so a poll costs a few round-trips.

FAQ · Troubleshooting

Common questions during integration.

The receive button doesn't appear after a request

Expected — requests become receivable only after the next settlement completes (overview().nextSettlementAt). Requests after orderCloseAt roll one round later.

estimateDeposit returns null

No settlement has run yet, so there is no reference price. Show "finalized after settlement".

deposit throws NOT_WHITELISTED

The wallet is not whitelisted. Route to onboarding; detect beforehand with myAccount().canInvest.

Transactions fail with INSUFFICIENT_GAS

User txs run on Sepolia and need a little Sepolia ETH. (Gas sponsorship is on the roadmap.)

Every read returns RPC_UNAVAILABLE

Likely hub-node (internal testbed) connectivity — check VPN/node status; public Bifrost nodes cannot substitute.

Getting test assets (USDC · JPYC)

Self-service via faucet() — a UniversalFaucet deployed per chain dispenses the deposit asset (max 10,000 per claim, 1-hour cooldown per address). Multichain: omnifi.faucet(chainId); single-chain: sdk.faucet(). See faucet().

Reading completed history

Use the low-level omnifi.inner.requestHistory() / receiveHistory() (paginated, max 50).

Glossary

Standard vocabulary for UI copy, aligned with the internal terminology spec.

Architecture and low-level access

What sits under the facade, and how to reach it.

The facade's activity()/phase combine Investments ("results") with TxRegistry ("progress"). The spoke (Sepolia) is the ERC-7540 vault standard — the source of truth for balances and receivables.

Call batching

Reads are batched internally — Multicall3 aggregation plus JSON-RPC HTTP batching on the spoke, JSON-RPC HTTP batching on the hub (no Multicall3 on the testbed chain). Consumer code just uses Promise.all; batching is automatic.

Environment

Current testbed configuration.

Canonical source: RWA-SDK/docs/USAGE.ko.md · verified live 2026-08-18