Wisp by Veru Finance

A multi-asset shielded pool on Stellar. Shield Stellar assets into one Merkle tree, move value privately, swap on Soroswap, earn in a DeFindex vault, borrow on Blend, and exit to any address. A zero-knowledge proof gates every step: circuits in Noir, proved with UltraHonk, verified by Soroban contracts.

Principles

• The browser holds every secret. Keys come from one wallet signature and live only in tab memory. Note secrets travel only inside memos encrypted to the receiver.
• The proof fixes every term. The note owner's EdDSA signature covers every public input: recipient, amount, asset, new notes, their memos, the relayer fee and any adapter or money-market spec. Servers can delay or refuse, never change.
• One key per note, one per loan. No two on-chain records share an owner hash.
• Internal moves are asset-blind. Send, split and merge reveal neither amount nor asset. Only boundary operations (shield, withdraw, swap, vault, money market) do, because tokens enter or leave the pool.
• A minimal pool. wisp_pool holds the tokens, the tree, the nullifiers and the asset registry. Adapters and Positions take a note's value by being its withdrawal's recipient.
• Screening with an exit. An ASP admits each deposit into the tree; until then the depositor can always take it back (ragequit).

What you can do

How it works

Every component and who talks to whom. Solid arrows are calls or requests; the dotted one is Prometheus scraping every service's metrics.

The four layers

• Browser. Holds the keys, finds notes, builds and proves every spend. Nothing secret leaves the tab.
• Off-chain services. The indexer serves public chain data; the relayer submits finished proofs and pays the network fee; the ASP screens deposits. They can stall, never steal or change a transaction.
• Soroban contracts. wisp_pool holds everything; adapters and Positions reach the venues; verifiers check proofs.
• Stellar DeFi. Soroswap, DeFindex and Blend, used unchanged.

Components

What each piece does, what it exposes, and where its code lives.

In the browser (web/)

Off-chain services

Soroban contracts (contracts/)

Notes, memos and keys

A note is a private record kept off-chain; only its commitment goes on-chain, with an encrypted memo only its owner can open. Every key comes from one wallet signature.

The note

The 172-byte memo

Every new leaf carries exactly one memo: a 32-byte one-time key E, a 16-byte stamp (an HMAC under the receiver's detection key, which the indexer can match but not read), and a 124-byte secret part encrypted to the receiver's view key (nonce + AES-256-GCM of a 96-byte plaintext + tag). The plaintext holds the kind (note or adapter output), secret, nullifier, amount, asset and the owner's key index.

Keys from one wallet signature

Receive address: wisp:<owner hash>:<detectPub>:<viewPub>:<index>. A bare G… or C… address is refused as a private target: a note sent there could never be spent.

Circuits

Seven Noir circuits, proved with UltraHonk (ZK flavor) in the browser and verified on Soroban.

Measured with bb.js 0.87.0 on 8 threads: transfer 3.5 s, split 5.5 s, merge 7.5 s. On-chain verification costs 113M–122M instructions of the 400M per-transaction limit. Toolchain: nargo 1.0.0-beta.9, pinned in tools/versions.env; artifacts pinned in circuits/manifest.json.

Quick start

Run Wisp locally against the live testnet deployment, then connect a wallet.

Prerequisites

• Node 22, Docker, and the repo's dependencies (npm ci).
• Built contracts (stellar contract build in contracts/) and compiled circuits (circuits/target/).

Run it

npm run dev      # Postgres, indexer, relayer, ASP service and the web app
# open http://localhost:5173 · Ctrl+C stops everything

cd web && npm run dev
#   wisp  indexer → http://127.0.0.1:8088, relayer → http://127.0.0.1:8088

docker compose -f ops/compose.yml -f ops/compose.behind-proxy.yml up -d --build

npm run e2e -w @wisp/web    # every flow in a real browser against testnet (~15 min)

Connect a wallet

1. Install Varial (the Stellar Development Foundation's wallet, formerly Freighter) and switch it to Testnet (the network name at the top, or Settings → Network). Wisp checks the network and says so if it's wrong. Without Varial, the app shows Install Varial instead.
2. Fund the account: curl "https://friendbot.stellar.org/?addr=G…".
3. Click Connect Varial, then Unlock private keys and approve the one signature (no transaction, no fee).

Using the app

A tour of every screen, and what each number means.

Overview cards

• Shielded balance per asset, from your spendable notes.
• Notes: spendable, screening and spent.
• Public balance: your wallet's XLM, read from Stellar RPC ("Not funded" for a new account).

Shield

Deposit from your account; the wallet signs. The deposit then waits for screening, about a minute on testnet; the page updates on its own when it's admitted, and until then you can take it back.

Send privately, split, merge

Send to a wisp: receive address (the receiver copies it from Receive). Split note previews both resulting notes after the 0.01 XLM fee; Merge notes joins two notes of one asset.

Withdraw

A whole note to any Stellar address. For classic assets such as USDC the recipient needs a trustline; if it's your own account, the app offers Add USDC to your wallet.

Swap

Pick a note and the token to receive; a Soroswap quote shows what you pay, about what you receive, the minimum (quote less 1%) and the rate, refreshed every 15 seconds. If less than the minimum would arrive, nothing is spent.

Vault

Your vault position shows the share price now, its change since your average entry (the index increase), your shares and their value, deposited and withdrawn, and profit or loss.

Money market

Each position shows, per asset: tokens × index = amount now, the net supplied or borrowed, and the interest earned (collateral) or owed (debt), plus net interest at oracle prices. Health and maximums keep a 5% margin above liquidation.

Transaction toasts

Every finished action shows a toast linking its transactions on Stellar Expert (two for swaps and vault moves).

Deploy

The web app is static and goes on Netlify; the backends need a server with a public IP and a domain.

1. Backends

export WISP_API_HOST=api.example.org WISP_ACME_EMAIL=ops@example.org
export WISP_APP_ORIGIN=https://<site>.netlify.app
docker compose -f ops/compose.yml -f ops/compose.public.yml up -d --build

# ops/.env: WISP_APP_ORIGIN=https://<site>.netlify.app
docker compose -f ops/compose.yml -f ops/compose.behind-proxy.yml up -d --build
sudo cp ops/nginx/wisp-stellar-api.conf /etc/nginx/sites-available/wisp-stellar-api
sudo ln -s /etc/nginx/sites-available/wisp-stellar-api /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d wisp-stellar.213-136-69-252.sslip.io --redirect

2. Web app on Netlify

VITE_INDEXER_URL=https://<api host>/index/v1 \
VITE_RELAYER_URL=https://<api host>/relay/v1 \
npm run build:netlify -w @wisp/web
npx netlify-cli deploy --prod --dir web/dist-netlify --site <site>

Or drag web/dist-netlify onto app.netlify.com/drop. The build refuses non-https URLs; _headers sets cross-origin isolation (fast proving), no framing, and revalidation for circuits.

3. Check

• curl https://<api host>/index/v1/health → "ok": true
• The app's bottom left reads Indexer: in sync and Relayer: ready.
• In the console, crossOriginIsolated is true.

Keys and unlock

One SEP-53 signature gives every key the wallet will use. The same account always gives the same seed, so a new device finds everything again.

sequenceDiagram
  autonumber
  actor U as User
  participant UI as Wisp app
  participant W as Wallet
  participant KR as Key ring (tab memory)
  participant LS as localStorage
  U->>UI: Connect Varial
  UI->>W: requestAccess, then getNetwork (must match)
  W-->>UI: G-address
  U->>UI: Unlock private keys
  UI->>W: signMessage(KEY_DERIVATION_MESSAGE), SEP-53
  W-->>UI: 64-byte Ed25519 signature
  UI->>W: signMessage again (first unlock on a device)
  W-->>UI: the same signature, or the wallet is refused
  UI->>KR: seed = keccak256("shield-bjj-v1" ‖ sig) mod p
  KR->>KR: note keys (seed,1,i) · position keys (seed,4,j) · view (5) · detection (6) · decoys (7)
  KR->>LS: view and detection keys, key book, decoys, receive index
  Note over KR: The seed and owner keys never leave tab memory
  

1. The wallet shares its address; Wisp checks its network.
2. On a device's first unlock the wallet signs twice and both must match, or its keys wouldn't be reproducible.
3. Only view-only material is stored: after a reload notes show ("View only"); spending needs Unlock again.

Note sync

How a wallet finds its notes and learns which are spent, without the indexer reading anything.

sequenceDiagram
  autonumber
  participant B as Browser (sync)
  participant IA as Indexer API
  participant SW as Stamp workers
  participant PG as Postgres
  participant P as wisp_pool
  B->>IA: POST /notes with the detection key
  IA->>PG: leaves after this key's watermark, in batches
  IA->>SW: check each 16-byte stamp under the detection key
  SW-->>IA: matching leaves
  IA->>PG: save matches and the new watermark, under an HMAC of the key
  IA-->>B: matching records with each adapter note's origin, and open outputs
  B->>B: open memos with the view key, derive the one key each names, recompute commitments
  B->>IA: POST /buckets with own buckets padded by decoys
  IA-->>B: every spent nullifier in those buckets
  B->>IA: GET /tree/chunk/n when building a spend
  IA-->>B: public leaves
  B->>P: is the rebuilt root known?
  P-->>B: yes, or the tree is refused
  

Shield and screening

Deposits move your own funds, so your wallet signs them. A deposit waits outside the tree until the ASP admits it.

sequenceDiagram
  autonumber
  participant B as Browser
  participant W as Wallet
  participant P as wisp_pool
  participant I as Indexer
  participant AS as ASP service
  participant A as wisp_asp
  B->>B: new note for a fresh own key, prove deposit
  B->>W: sign deposit(depositor, asset, amount, note, proof)
  W->>P: transaction, the wallet authorizes the token transfer
  P->>P: verify, take the tokens (balance re-checked), store as pending
  P-->>I: deposit_pending event
  loop every few seconds
    AS->>I: GET /deposits/pending, the same list for everyone
    AS->>P: confirm it's still pending
    AS->>AS: at least 12 ledgers old, depositor not denylisted
  end
  alt passes
    AS->>A: admit(commitments)
    A->>P: admit: insert leaves, emit note_memo
    B->>I: watcher sees it leave the pending list, syncs
  else rejected
    AS->>A: reject(commitments, reason)
  end
  opt before admission
    B->>W: sign ragequit(commitment)
    W->>P: ragequit: exactly the amount back
  end
  

Send privately

To a receive address. A whole-note send is a shielded_transfer; anything less is a split with change back to you.

sequenceDiagram
  autonumber
  participant RB as Receiver's browser
  participant S as Sender's browser
  participant R as Relayer
  participant P as wisp_pool
  participant I as Indexer
  RB-->>S: receive address wisp:ownerHash:detectPub:viewPub:index
  S->>S: receiver note, change note (fresh own key), fee note to the relayer
  S->>S: memos, memoHash, EdDSA signature, prove split_transfer
  S->>R: POST /relay/v1/submit
  R->>R: allowlist, decode, open the fee memo, fee at least 0.01 XLM, simulate
  R->>P: submit from a channel account, the relayer pays the network fee
  P->>P: root known, nullifier unused, verify, insert 3 leaves
  P-->>I: note_memo events
  RB->>I: POST /notes
  I-->>RB: the new record, opened locally
  

Split and merge

Reshape your own notes. On chain both look like any private transfer.

Split

flowchart LR
  N["Your note
1.99 XLM"] --> SP{{"split_transfer proof
signed by the note's key"}}
  SP --> A["Note A · 0.49 XLM
fresh own key"]
  SP --> B2["Note B · 1.49 XLM
fresh own key"]
  SP --> F["Fee note · 0.01 XLM
to the relayer"]
  

Merge

flowchart LR
  L["Note left"] --> MP{{"merge_transfer proof
signed by both owners' keys"}}
  RR["Note right"] --> MP
  MP --> O["Merged note
fresh own key"]
  MP --> F["Fee note
to the relayer"]
  

Both merged notes must share a tree root and an asset; the circuit checks left + right = output + fee.

Withdraw

A whole note to any Stellar address, as a public amount of one asset.

sequenceDiagram
  autonumber
  participant B as Browser
  participant RPC as Stellar RPC
  participant W as Wallet
  participant R as Relayer
  participant P as wisp_pool
  participant T as Token contract
  B->>RPC: classic asset? do the recipient and relayer have its trustline?
  alt your own account lacks the trustline
    B->>W: sign changeTrust (public, 0.5 XLM reserve)
  end
  B->>B: prove transfer: recipient, amount, asset, relayer, fee, specHash = 0
  B->>R: submit private_transfer
  R->>P: fee checked, simulated, submitted
  P->>T: amount minus fee to the recipient, fee to the relayer
  

Swap

The output amount is only known when the swap runs, so the browser fixes the future note's key and preimages in advance (the seal), inside the signed spec.

sequenceDiagram
  autonumber
  participant B as Browser
  participant R as Relayer
  participant SA as swap_adapter
  participant P as wisp_pool
  participant SS as Soroswap router
  B->>SS: quote: what the note less the fee would give
  B->>B: SwapSpec: asset out, min_out (quote less 1%), path, deadline, seal, memoHash
  B->>R: submit swap(proof, w, spec, memo)
  R->>SA: submit
  SA->>P: private_transfer, the adapter is caller and recipient
  SA->>SS: swap, authorizing exactly the router's pull
  SS-->>SA: output, kept only if at least min_out
  B->>B: prove sealed_deposit(amount out, asset, key K, seal)
  B->>R: submit finalize
  R->>SA: submit
  SA->>P: deposit_sealed: your new note
  

The quote

The Swap tab shows Soroswap's quote before you confirm: you pay (the note less the 0.04 XLM fee), you receive about, at least (quote less 1%) and the rate. The swap uses the same quote function. On testnet, the quote, the router and the amount received matched exactly.

Vault

The same two phases with DeFindex. Shares stay shielded as dfXLM notes (pool asset 3).

sequenceDiagram
  autonumber
  participant B as Browser
  participant R as Relayer
  participant YA as yield_adapter
  participant P as wisp_pool
  participant DX as DeFindex vault
  B->>R: submit open(proof, w, VaultSpec, memo)
  R->>YA: submit
  YA->>P: private_transfer to itself
  YA->>DX: deposit (XLM in, shares out) or withdraw (shares in, XLM out)
  DX-->>YA: output, held by the adapter
  B->>R: submit finalize with a sealed_deposit proof
  YA->>P: deposit_sealed: the output becomes your note
  

Your vault position

share price   = managed funds ÷ shares outstanding        (read live)
entry price   = XLM deposited ÷ shares received          (your vault events)
profit / loss = value of shares now + XLM withdrawn − XLM deposited

Deposits and withdrawals come from each note's origin, the public event that created it, so the numbers are the same on any device. Amounts are before relayer fees.

Money market

Each loan gets its own Position contract and key. Money in is authorized by a note owner; money out only by the position key.

Fund: supply or repay

sequenceDiagram
  autonumber
  participant B as Browser
  participant R as Relayer
  participant M as position
manager
  participant Pos as Position (key j)
  participant P as wisp_pool
  participant BL as Blend pool
  B->>B: FundingSpec (key hash, 0 supply or 1 repay), prove transfer to the Position
  B->>R: submit fund(proof, w, spec)
  R->>M: submit
  M->>Pos: deploy on first funding (salt = key hash), then pull
  Pos->>P: private_transfer, the Position is caller and recipient
  Pos->>BL: supply collateral, or repay (surplus supplied)
  

Outflow: borrow or withdraw collateral

sequenceDiagram
  autonumber
  participant B as Browser
  participant R as Relayer
  participant M as position
manager
  participant Pos as Position
  participant BL as Blend pool
  participant P as wisp_pool
  B->>B: OutflowSpec with nonce, deadline, fee and the output note fixed in advance
  B->>B: prove position_auth and sealed_deposit
  B->>R: submit outflow
  R->>M: submit
  M->>M: verify position_auth, check and use the nonce
  M->>Pos: submit
  Pos->>BL: borrow, or withdraw collateral (Blend checks health)
  M->>P: deposit_sealed: the rest becomes your note, the fee goes to the relayer
  

Interest

amount now   = Blend tokens × index        (b_rate for collateral, d_rate for debt)
principal    = net supplied, or net borrowed   (the position's public events)
interest     = amount now − principal          (earned on collateral, owed on debt)

The browser reads the position events from the indexer's public feed and keeps its own locally, so the indexer can't tell which positions are yours. A repayment that also paid interest counts against principal, a small approximation.

Indexer

One ingest worker turns contract events into Postgres rows; the API serves public data and stamp matches.

flowchart TD
  A["getEvents from the cursor
up to 500 events, at most 10,000 ledgers"] --> B["decode"]
  B --> C{"from the contract
that may emit it?"}
  C -- no --> H["INGEST HALTED"]
  C -- yes --> D{"leaves contiguous,
roots match?"}
  D -- no --> H
  D -- yes --> E["one transaction:
rows + cursor + scanned-to ledger"]
  E --> F{"events on this page?"}
  F -- yes --> A
  F -- no --> G["wait POLL_MS"] --> A
  A -.->|"RPC or database error"| X["retry, backoff up to 30 s"]
  X -.-> A
  

• Only consistency guards stop ingest; everything else is retried.
• The scanned-to ledger is the one each page's cursor reached: a quiet pool shows no lag, a catching-up indexer its real lag.
• First syncs spread stamp checks over worker threads (STAMP_WORKERS): 11.4 s → 1.7 s p95 at 50,000 leaves.

Relayer

Its checks protect its own fees; the proof already protects the user. It can delay or refuse, never change a term.

flowchart TD
  A["POST /relay/v1/submit"] --> B{"contract and function
allowlisted?"}
  B -- no --> X["403"]
  B -- yes --> C["decode args"]
  C --> D{"fee terms"}
  D -->|"send · split · merge"| D1["open the fee note's memo,
at least minFeeNote"]
  D -->|"withdraw · fund · outflow"| D2["public fee to this relayer"]
  D -->|"swap · vault phase 1"| D3["at least minAdapterFee"]
  D -->|"finalize · cancel"| D4["no fee"]
  D1 & D2 & D3 & D4 --> E["simulateTransaction"]
  E --> F{"no authorization needed,
fee under the cap?"}
  F -- no --> X2["422"]
  F -- yes --> G["margins, least-busy channel account"]
  G --> H["send, poll until final, 200"]
  

Fees (testnet)

Allowlist: pool shielded_transfer, shielded_split_transfer, shielded_merge_transfer, private_transfer; swap swap, finalize; vault open, finalize; manager fund, outflow, cancel_authorization. Deposits are never relayed.

ASP service

Screens pending deposits and admits or rejects them through wisp_asp. Stateless: every decision is on chain.

flowchart TD
  A["every POLL_MS"] --> B["GET /deposits/pending"]
  B --> C["confirm each against the pool"]
  C --> D{"policy"}
  D -->|"denylisted"| R["wisp_asp.reject
(still ragequittable)"]
  D -->|"younger than 12 ledgers"| WT["wait"]
  D -->|"passes"| AD["wisp_asp.admit, up to 5 per batch"]
  

Testnet policy: minimum age 12 ledgers, batches of 5, an empty denylist. If it stops, deposits wait, and depositors can still take them back.

API reference

JSON over HTTPS. Amounts are raw token units as strings; hashes and keys are 0x hex. Errors are {"error": {"code", "message"}}.

Indexer /index/v1

Records whose stamps match a detection key, from this key's watermark. Access logs off.

→ { "detectionKey": "0x…64 hex" }
← { "scannedTo": 205,
    "notes": [{ "leafIndex": 94, "commitment": "0x…", "ownerHash": "0x…", "memo": "0x…", "ledger": 5462822,
                "publicAmount": "…", "publicAssetId": 3,
                "origin": { "venue": "vault", "deposit": true, "assetIn": 1, "amountIn": "29600000",
                            "assetOut": 3, "amountOut": "17749" } }],
    "outputs": [{ "id": "0x…", "venue": "swap", "ownerHash": "0x…", "memo": "0x…", "assetId": 4, "amount": "…", "ledger": … }] }

→ { "bits": 7, "buckets": [3, 17, 88] }      // bits 0..24, 1..256 buckets
← { "nullifiers": [{ "nullifierHash": "0x…", "ledger": 5452010 }] }

/head         ← { "lastLedger", "leaves", "root", "nullifiers", "bucketBits" }
/health       ← { "ok": true, "lastLedger", "latestLedger", "lagLedgers": 0 }
/tree/chunk/0 ← { "chunk": 0, "chunkSize": 1024, "leaves": ["0x…", …] }

← { "deposits": [{ "commitment", "depositor", "assetId", "amount", "ledger", "txHash", "rejected": null }], "next": null }

← { "events": [{ "id", "kind": "position_funded", "ledger", "txHash",
                 "data": { "action": 0, "amount": "199800000", "asset_id": 1, "position": "C…" } }],
    "next": "5451551:0023414233257529344-0000000007" }

Relayer /relay/v1

→ { "contract": "C…", "fn": "shielded_split_transfer", "args": ["base64 XDR", …] }
← { "hash": "…64 hex", "ledger": 5465073 }
✕ { "error": { "code": "simulation_failed", "message": "contract error #13", "contractError": 13 } }

Refusals: contract_not_allowed, function_not_allowed (403); bad_args (400); fee_not_ours, fee_unreadable, fee_mismatch, fee_asset, fee_too_low, simulation_failed, needs_authorization, fee_cap (422); send_failed, tx_failed (502); rate_limited (429).

/info   ← { "address": "G…", "pool": "C…", "feeReceiveAddress": "wisp:…", "functions": […],
            "adapters": { "swap": { "id", "functions" }, … }, "minFeeNote", "minWithdrawFee", "minAdapterFee" }
/health ← { "ok": true, "balance": "99884085482", "floor": "100000000", "channels": 1 }
/status/<hash> ← { "status": "SUCCESS" | "FAILED" | "NOT_FOUND", "ledger"? }

ASP /asp/v1

/policy ← { "asp": "C…", "operator": "G…", "minAgeLedgers": 12, "maxBatch": 5, "denylistSize": 0, "ragequit": "…" }
/health ← { "ok": true, "lastRun": { … } }

Testnet deployment

Stellar testnet (passphrase Test SDF Network ; September 2015), RPC https://soroban-testnet.stellar.org. Deployed 2026-10-29 at ledger 5451356; source of truth: deployments/testnet.json.

Contracts

Verifiers

Assets

Venues and accounts

Limits

• Soroban per-transaction CPU limit 400M; ZK verification about 120M, a depth-20 insert about 22.5M.
• RPC keeps about 7 days of events, scanned at most 10,000 ledgers per request.
• The last 128 roots (plus each full tree's final root) stay valid.

Hosting

The Docker stack

flowchart TB
  U["Browser on Netlify"] -->|"https://api host"| PX["nginx or Caddy
TLS"]
  subgraph host["Docker compose · wisp-stellar"]
    CAD["Caddy · routing"]
    IA["indexer-api :4200"]
    IG["indexer-ingest"]
    RL["relayer :4300"]
    AS["asp :4400"]
    PG[("postgres")]
    PR["prometheus 127.0.0.1:9095"]
  end
  PX --> CAD
  CAD -->|"/index/v1/*"| IA
  CAD -->|"/relay/v1/*"| RL
  CAD -->|"/asp/v1/*"| AS
  IA --> PG
  IG --> PG
  PR -.->|"/metrics, internal only"| IA & RL & AS
  

The dev stack

flowchart LR
  L["npm run dev"] --> PGD[("Postgres :5432")]
  L --> IGD["ingest, creates tables"]
  IGD -->|"then"| IAD["indexer API :4200"]
  IGD -->|"then"| RLD["relayer :4300"]
  IGD -->|"then"| ASD["ASP :4400"]
  IGD -->|"then"| VITE["Vite :5173
proxies the APIs"]
  BR["Browser, forward only :5173"] --> VITE
  

Monitoring and alerts

Every alert has a promtool rule test in CI (ops/prometheus/alerts.test.yml); all but DepositsWaitingLong have fired and resolved in live drills.

Runbooks and tools

Runbooks (docs/runbooks/)

• indexer-stuck: halts, lag, slow first syncs, re-ingesting.
• relayer-drained: low balance, trustlines, rejections.
• asp-down: deposits waiting, ragequit as the exit.
• contract-bug: pausing deposits, upgrades, replacing contracts without an upgrade path.
• ttl-and-reset: TTL extensions and testnet resets.

Deployment tools (packages/wisp-testnet/scripts/)

What is public

Trust model

Security review

An internal review by the builders, not an audit. Full text: docs/security-review.md.

Decisions

Settled design choices, in docs/decisions/.

Glossary