Technical Whitepaper
Localcredit
A Universal Credit Rating Oracle
Technical Whitepaper (2025) This technical whitepaper outlines the full system architecture, core components, scoring algorithm, frontend, developer APIs, and implementation details required for production deployment. Introduction
Traditional credit systems remain geographically siloed and institution-centric, excluding billions from formal finance. Decentralized finance has largely relied on over-collateralization due to the absence of reliable reputation primitives. Localcredit solves this by creating a neutral, universal trust oracle that aggregates verifiable financial behaviors into a portable, cryptographically provable score. The protocol is chain-agnostic, privacy-first, and designed as an infrastructure primitive rather than a lending platform. Objectives
Deliver a dynamic credit score (0–1000) based on long-term behavioral patterns.
Ensure voluntary participation with strict data minimization and ZKP-based verification.
Enable third-party applications (lending protocols, marketplaces, etc.) to query scores and report outcomes for continuous model improvement.
System Architecture
Localcredit follows a layered, modular design:
Frontend Layer.
Identity & Verification Layer – ZKP-based attribute proofs.
Data Ingestion Layer – On-chain indexers and decentralized oracles.
Analytics & Scoring Layer – Secure off-chain compute with ZK-provable outputs.
Oracle & Query Layer – Smart contracts for score publication and paid queries.
Governance & Feedback Layer – DAO and lender reporting dashboard.
Primary deployment: TON blockchain with cross-chain oracles for EVM and other ecosystems. Smart contracts are written in Solidity (EVM) and FunC/Tact (TON), fully audited and open-source.
Frontend: The core user experience is delivered through a Telegram Mini App and web interface accessible via @LocalcreditBot. This leverages Telegram’s 1 billion+ user base and native TON wallet infrastructure for frictionless onboarding and viral distribution. Tech Stack
Framework: React.js + Vite
Telegram SDK: @tma.js/sdk
Web3: TON Connect SDK (@tonconnect/ui-react)
Styling: Tailwind CSS (synced with Telegram themes)
Hosting: Vercel + IPFS fallback
Key Features
Seamless TON wallet connection via TON Connect (Tonkeeper, @wallet, etc.).
Multi-wallet linking (EVM/Solana via signed messages and oracles).
Onboarding flows for email, phone, X (Twitter), and optional KYC/AML.
Real-time dashboard showing score, history, risk profile, and simulation tools.
Full-screen mode with Telegram-native UI elements (popups, haptic feedback).
Core Components
1. Wallet Connection & Multi-Wallet Support
Users prove ownership of multiple wallets (TON, EVM, Solana) via signed messages. Linkages are aggregated into a single abstract identity using Merkle proofs and stored on-chain.
2. Social Media (X) Linkage
OAuth2 flow + signed challenge tweet or private verification. ZKP proves ownership and account age/activity without exposing the handle.
3. Email & Phone Verification
OTP delivery (SendGrid/Twilio) → signed confirmation. Only ZK proofs stored.
4. AML/KYC Bot Integration
Tiered compliance via third-party providers (Chainalysis, Elliptic, or Persona). Documents processed ephemerally; only boolean ZK attestations persisted (e.g., “not sanctioned”, “age ≥18”).
5. On-Chain Activity Monitoring
Indexers (The Graph, Covalent, TON RPC) track repayments, transaction patterns, wallet age, and protocol interactions. Cross-chain data aggregated via LayerZero/CCIP oracles.
6. Lender Reporting Dashboard
Web + Mini App interface for lenders to submit signed outcome reports (repaid/defaulted). Reports anonymized via ZK and used for model retraining.
7. Credit Limit Estimation & Risk Profile
Dynamic outputs derived from score, including suggested USD limit and categorical risk tier.
Scoring methodology:
Repayment and Obligation Fulfillment Measures how consistently a user meets financial obligations, including loan repayments, recurring commitments, and agreed payment schedules observed through on-chain data and verified attestations. It emphasizes timeliness, completion, and recovery rather than binary default events.
Behavioral Consistency and Continuity Evaluates the regularity and stability of a user’s financial activity over time. Long-lived wallets, consistent transaction patterns, and sustained participation across economic cycles signal reliability in ways traditional scores cannot capture. Identity Strength and Persistence Reflects the depth and durability of a user’s abstract identity as established through the privacy-preserving identity layer. Signals such as long-term wallet usage, verified communication channels, and persistent identity linkages increase confidence that observed behavior belongs to the same individual over time.
Cross-Context Behavior Integration Aggregates behavior across multiple platforms, applications, and environments rather than isolating activity within a single institution or jurisdiction. This allows the score to reflect how a person behaves across their full economic life.
Adaptive Weighting and Time Sensitivity The scoring model adjusts the relative importance of signals based on recency and long-term trends. Recent behavior influences access decisions, while long-term history provides stability and resilience against short-term shocks.
Transparency and Verifiability The scoring logic is transparent and auditable, allowing users and integrators to understand how inputs influence outcomes. Users can simulate how behaviors affect their score, reinforcing the idea that reputation is earned, inspectable, and improvable.
Together, these components ensure that the credit score reflects a person’s financial journey rather than a static institutional snapshot. It captures reliability as it is lived: gradually, contextually, and across borders.
Scoring Algorithm
The score is computed off-chain (secure compute nodes, e.g., Phala Network) and published with ZK proofs. Inputs (normalized 0–1)
I – Identity strength (wallet age, verified channels, KYC tier)
B – Behavioral consistency (repayments, transaction stability)
C – Continuity across contexts and chains
R – Risk signals (AML flags, volatility)
Formula S = 100 × (w_I × I + w_B × B + w_C × C - w_R × R) / Σw
w_I = 0.20, w_B = 0.40, w_C = 0.20, w_R = 0.20 Time decay is applied exponentially (λ ≈ 0.01/day) to emphasize recency while preserving long-term history. Repayment sub-model uses logistic regression trained on lender-reported outcomes.
Risk profile generated via Monte Carlo simulation of default probability. All outputs ZK-provable using Groth16 circuits. Developer Integration & API
Localcredit provides comprehensive, well-documented APIs for third-party applications to query scores and integrate trust signals.
Billing Model
Queries and subscriptions paid in $CREDIT token. Lending apps must hold $CREDIT in a connected wallet; costs deducted automatically.
On-Chain Queries (DeFi-native)
Call LocalcreditOracle contract:
requestScore(bytes32 userProof) → (uint256 score, bytes proof)
REST/GraphQL API (Web & Mini Apps)
Base URL: https://api.localcredit.org/v1
Key Endpoints:
GET /score/{proof} – Fetch score and risk profile
POST /reportOutcome – Submit anonymized loan results
POST /subscribe – Create recurring subscription
Authentication: API key + signed TON message.
Documentation & SDKs
Hosted at docs.localcredit.org with:
Interactive Swagger/OpenAPI playground
SDKs: JavaScript (Mini Apps), Solidity, Python
Example integrations and billing dashboards
Security & Privacy
All personal data processed ephemerally; only ZK proofs stored.
Sybil resistance via proof-of-personhood signals and governance-tuned thresholds.
Oracle slashing mechanisms for bad data.
Full contract audits required before mainnet.
Last updated