Proven — The trust layer for GIWA

01

The stack at a glance

Six contracts. One chain.

Everything Proven owns is deployed and verifiable on GIWA Sepolia. The two upstream contracts are GIWA's — we read them, we never rebuild them.

Chain / stack

91342

GIWA Sepolia · OP Stack

Compiler

0.8.28

optimizer on · evm paris

Our contracts

6

score · vault · factory · pool · TKRW · TUSD

Attestations read

4

addr · balance · age · code

Libraries

OZ v5

ERC-4626 · ERC-20 · Math

Toolchain

HH 2.29

deploy · redeploy · verify

Frontend

vanilla

ethers v6 · zero build step

PII on-chain

0

signed booleans only

02

Tier B · the trust engine

DojangScore V2 · Provenance-ceiling engine

V2 introduces the provenance ceiling: a wallet's score can never exceed the strength of its strongest proof. A sybil farm can grind to Silver, but cannot buy Platinum.

Provenance classes · ranked

Four classes, four ceilings

score(w) = min(ceiling(provenance_class), Σ category_scores)
// ceiling is the hard cap set by the strongest proof class —
// no amount of lower-class signals can break through it

ATTESTER — regulated attester (Upbit/Dojang) → ceiling 1000 Platinum
CONSENTED — self-submitted proofs (ENS, Passport, OAuth) → ceiling 799 Gold
BEHAVIORAL — reporter-attested on-chain activity → ceiling 499 Silver
STATE — trustless on-chain state (holds LP/vault shares) → ceiling 499 Silver

Tiers · downstream effect

One number, many gates

Standard <200 · Silver 200–499 · Gold 500–799 · Platinum 800–1000.
tierOf() / tierName() are the only calls consumers need.
scoreBreakdown() returns per-category detail: baseAttestation, trustlessState, reporterActivity, consentedProofs.
Graceful reads: every upstream call is try/catch-wrapped — a missing or revoked proof degrades a score, never reverts a query.
V1 required Upbit; V2 accepts any whitelisted attester — the ceiling stays high, the door gets wider.

A sybil farm can grind to Silver, but cannot buy Platinum.the provenance ceiling · DojangScore V2

03

Tier C · the yield engine

WonVault

A standard ERC-4626 tokenized vault — which is the whole point: any wallet, aggregator or router integrates with zero custom code, and the accounting is audited library code, not hand-rolled.

Share-price engine

Yield = the price rising

sharePrice = (assets + virtualAssets) / (shares + virtualShares)
// yield enters as assets growing while shares stay flat
// → every existing share redeems for more

_decimalsOffset() = 18 injects virtual shares + assets — the inflation / first-depositor protection (Morpho · Euler v2 · OZ).
deposit() skims the tiered entry fee to treasury, then hands the net to super.deposit() so the share math is the library's, verbatim.
Testnet yield is simulated (open mint() into the vault) so the engine is visible on camera; mainnet removes the open mint and gates value through a role-controlled harvest().

The scar we ship with

The 1e21, told in three steps

① deposit minted 0 shares

With the offset off, an empty vault took the assets and issued no receipt — money in the box, ownerless.

② price → 1.09e+21

Trapped assets ÷ ~0 shares = astronomical. The "any shareholders?" guard saw supply 0 and refused, while 1194 TKRW sat inside.

③ redeploy + reader clamp

_decimalsOffset()=18 closes the rounding attack; the dashboard refuses to render an out-of-band price (— / "degraded") — defense-in-depth that caught it before real money.

04

Tier C · the trading floor

GIWASwap

Factory + Pool, constant-product, with the one feature no other chain can offer: the swap fee is a function of the swapper's trust tier.

Pricing · exact

x · y = k, trust-discounted

afterFee = amountIn * (10000 − feeBps) / 10000
amountOut = afterFee * rOut / (rIn + afterFee)
// require(amountOut >= amountOutMin) → slippage guard

Factory enforces A≠B, non-zero, no duplicate pair; canonical ordering token0 < token1.
Pool is itself the LP token (GLP); first mint locks sqrt(a·b) − 1000 permanently.
Reserves recompute from balances on every action — they cannot drift.

Why it can't be ported

The moat is the attester

feeBpsFor(swapper) reads DojangScore — needs Dojang + Upbit, which exist only on GIWA.
GIWA's ~200ms Flashblocks make the swap feel instant — a real UX edge on top of the fee edge.
The DEX's strategic role is foundational liquidity + price discovery + a verification flywheel, not just fee P&L.

05

The single source of truth

One verification, three discounts.

Every fee in the suite is a pure function of the same tier. Pick a tier — the column lights up across all three protocols.

Signal / protocol	Standard	Silver	Gold	Platinum
DojangScore range	0–199	200–499	500–799	800–1000
Provenance ceiling	NONE	BEHAVIORAL	CONSENTED	ATTESTER
WonVault entry fee	2.00%	1.50%	1.00%	0.50%
WonVault kept at work	98.00%	98.50%	99.00%	99.50%
GIWASwap fee	0.30%	0.20%	0.15%	0.10%

Read it as a flywheel: the discount is the incentive to verify; verifying raises the chain's own verified-user KPI and Sybil resistance; a cleaner chain makes the next user more willing to verify. The fee schedule is the growth model.

06

How it shipped

Execution pipeline.

Reproducible from a clean clone. The deployer key lives only in a git-ignored .env; nothing secret ever reaches the repo or the host.

Write

Solidity 0.8.28 · OZ v5 imports

Compile

hardhat compile · optimizer 200

Deploy

deploy.js → 6 contracts + LP seed

Patch

redeploy-vault.js → offset fix

Verify

verify-all.js → source on explorer

Serve

frontend/ → Vercel · HTTPS

Secret hygiene

Never in git

.env git-ignored; .env.example is the committed twin.
Vercel deploys only frontend/ — the root (and the key) never ships.

Frontend

Zero build

Single-file pages · ethers v6 via CDN · no bundler to misconfigure.
Live reads + writes; copy-to-clipboard on every address.

Reproducibility

From clone to chain

npm i → compile → deploy --network giwa.
deployed-addresses.json records every output.

07

Threat model

Shipped vs. roadmap.

The honest split: what protects real money today, and what mainnet adds before a single won is at risk.

Risk / attack	Mitigation	Status
ERC-4626 inflation / first-depositor	`_decimalsOffset()=18` virtual shares+assets; reader refuses out-of-band price	shipped v1
Open mint = donation surface	Remove on mainnet; value via role-gated `harvest()` only	roadmap
Attester / oracle manipulation	TWAP / Chainlink / Pyth, never spot; 90-day attestation expiry + refresh	roadmap
Strategy bleed (Euler v1 class)	Per-strategy isolation + debt caps + auto-quarantine loss cap	roadmap
Owner key compromise	Owner-gated params today; Safe multisig + guardian emergency brake	roadmap
Malicious ERC-20 in pools	Reserves from balances; roadmap allowlist + safe-transfer checks	roadmap
Upstream read failure	Every Dojang/EAS call `try/catch`-wrapped → graceful degradation	shipped v1

The dashboard is not decoration. It is the instrument that caught a real accounting exploit before real money was at stake — and the same discipline now gates what we promise on mainnet.the Proven engineering principle

08

The B2B product

The API Layer

One call returns a wallet's trust score, tier, and provenance. Use it to gate, weight, or price anything off-chain: launchpad allocations, airdrop multipliers, trading fees.

REST endpoints

Four routes, full coverage

GET /api/score/{address}
GET /api/tier/{address}
POST /api/score/batch // max 500 addresses
GET /api/health

Auth via x-proven-key header — no wallet signing required.
45-second cache per address — fast reads, no chain hammering.
Batch endpoint handles up to 500 addresses per call for bulk screening.

Rate tiers · B2B

Start free, scale to custom

Pilot — 1,000 calls / month, free. No credit card.
Builder — 50,000 calls / month. Production-ready.
Scale — custom limits, SLA, dedicated support.

The API is the B2B product; the suite is the proof that it works. Every on-chain contract is live evidence that the score is real and the tiers are enforced.

09

Protocol funding · community

Sustainability

The soulbound NFT funds protocol development and rewards early believers — without touching the trust score.

Soulbound supporter NFT

5,555 cap · $5 USDC

Hard cap of 5,555 tokens — soulbound, non-transferable.
Mint price: $5 USDC. 100% of proceeds fund protocol development.
Holders receive fee discounts across the suite and governance voice on parameter proposals.

Trust purity guarantee

Benefits, not score

NFT ownership grants benefits (discounts, governance) — it does not influence the DojangScore.
Trust stays pure: a whale with 100 NFTs gets the same score as an honest first-timer.
The ceiling is provenance. The perks are loyalty. They never mix.