Reputation & Scoring

Reputation is the trust context layer. It determines what execution paths are available to you, how much friction you see in the UI, and whether proof-gated flows will clear. Think of it as a DeFi credit score — except it's computed from on-chain data and backed by zero-knowledge proofs.

How scoring works

Your composite reputation score is computed from three signal families:

flowchart LR
  H["On-chain history<br/><i>tx count, age, diversity</i>"] --> R["Composite<br/>reputation score"]
  C["Collateral posture<br/><i>health factor, LTV, balance</i>"] --> R
  P["Proof completions<br/><i>FICO-pack proofs generated</i>"] --> R
  R --> G["Gating decisions"]
  R --> PR["Profile trust view"]
  R --> CR["Credit eligibility"]

• On-chain history — transaction count, wallet age, protocol diversity. This is read from your Starknet activity.
• Collateral posture — current health factor, loan-to-value ratio, asset composition. Changes in real time.
• Proof completions — which of the five FICO-pack proofs you've generated and verified. More proofs = higher trust.

The score affects:

• Gate outcomes in Trade Desk and controlled flows — lower reputation means more friction or outright blocking
• Trust posture displayed on /profile — the UI adapts to your tier
• Credit and lending eligibility — some lending paths require minimum reputation
• Remediation guidance — when a path is blocked, the system tells you what to improve

A more segregated V2 score model (separate reputation, credit, and governance domains) is planned. Today it's a single composite layer with proof-backed extensions.

FICO-pack proofs

These are the five zero-knowledge reputation proofs. Each one proves a specific financial property about your wallet without revealing the underlying data. They're verified on Starknet via Garaga BN254 verifiers and registered in ObsqraFactRegistry.

Proof	What it proves	Endpoint
Solvency	Your total assets are greater than or equal to your total liabilities. "I can pay what I owe."	POST .../proof/solvency
Risk Passport	Your risk tier is at or below the required tier for the action. "I'm not too risky for this."	POST .../proof/risk-passport
Trader Performance	Your Sharpe ratio, max drawdown, and win rate are all within acceptable bounds. "I know what I'm doing."	POST .../proof/performance
Strategy Integrity	Your positions, leverage, and slippage are within your declared policy. "I'm following my own rules."	POST .../proof/strategy-integrity
Execution Integrity	The delay between your transaction submission and inclusion, and the price deviation, are within bounds. "I'm not being front-run or sandwiched."	POST .../proof/execution-integrity

Request bodies in brief

Each proof endpoint expects specific inputs. Here's what they need:

• Solvency: user_address, asset_positions[] (address + balance pairs), debt_positions[], min_solvency_ratio_bps (basis points)
• Risk passport: user_address, volatility_bps, max_drawdown_bps, concentration_bps, effective_leverage_bps, liquidation_events, tenure_days, required_tier
• Performance: user_address, returns_bps (30 daily values), equity_curve (30 values), plus threshold params for Sharpe, drawdown, win rate
• Strategy integrity: user_address, position_weights_bps[], effective_leverage_bps, observed_slippage_bps[], plus policy bounds
• Execution integrity: user_address, submission_block, inclusion_block, expected_price, actual_price, max_delay_blocks, max_price_deviation_bps

Each returns a circuit scan result: all_pass (boolean), results[] with per-circuit success, proof hash, and timing.

Checking proof status

GET /api/v1/zkdefi/reputation/proofs/{address}

Returns the status of all five proofs: proof_type, status (complete | pending | available), generated_at, proof_hash, and on_chain_verified. This is the endpoint the profile page uses to show your FICO-pack completion.

Tier upgrades

Upgrading your reputation tier is a three-step process:

1. Generate the required proofs for the target tier. Each tier has minimum proof requirements — higher tiers require more of the five FICO-pack proofs.
2. Request the upgrade: POST /api/v1/zkdefi/reputation/upgrade-tier with address, target_tier, and upgrade_proof_hash.
3. Backend validates the proofs, updates your tier, and the change reflects on your profile immediately.

All endpoints

Method	Endpoint	What it does
GET	/api/v1/zkdefi/reputation/tiers	Tier definitions — what's required for each tier
GET	/api/v1/zkdefi/reputation/user/{address}	Your reputation snapshot — tier, score, history
GET	/api/v1/zkdefi/reputation/proofs/{address}	Status of all 5 FICO-pack proofs
POST	/api/v1/zkdefi/reputation/upgrade-tier	Request tier upgrade
POST	/api/v1/zkdefi/reputation/staking/stake	Stake for reputation (optional boost)
POST	.../proof/solvency	Generate solvency proof
POST	.../proof/risk-passport	Generate risk passport tier proof
POST	.../proof/performance	Generate trader performance proof
POST	.../proof/strategy-integrity	Generate strategy integrity proof
POST	.../proof/execution-integrity	Generate execution integrity proof
POST	/api/v1/zkdefi/lending/proof/credit-eligibility	Credit eligibility proof (related, not part of FICO-pack)

Under the hood

Proofs use BN254 Poseidon hashing. Private inputs (positions, returns, equity curves) are not sent to the API in the clear — the backend builds witnesses from on-chain data and runs the circuits server-side. The proof is generated over real data, not user-supplied inputs that could be falsified.

Verifier contracts are on Starknet Sepolia. See Contracts for the five FICO-pack verifier addresses. Circuit spec: circuits/REPUTATION_V1_CIRCUIT_SPEC.md.