Sanad Protocol

Landing page
Dashboard

Inspiration

We kept running into the same wall.

A friend of mine runs a pawnshop in Lagos. He told me about a customer who had taken three separate Aave loans, repaid every single one on time, and still couldn't get financing because the pawnshop had no way to check any of that. The guy's on-chain history was invisible. He was creditworthy on Ethereum and invisible everywhere else.

That stuck with me.

We started digging and found out the problem is even bigger than we thought. There's something like 50,000+ pawnshops across emerging markets, and most of them operate on pure cash and trust. A borrower walks in with gold, the pawnshop appraises it, hands over cash, and hopes for the best. The pawnshop's entire lending capacity is limited by whatever cash is sitting in the drawer that week. Meanwhile, the same borrower might have a perfectly good DeFi history sitting on Ethereum that nobody can see.

The Islamic finance angle made it more interesting. Gold-backed lending is a natural fit for Shariah-compliant finance — you've got real collateral, real custody, no interest. But the infrastructure isn't there. The IFSB puts total Islamic financial services assets at around \$3.88 trillion, and a lot of that is still waiting for better tools.

So we asked ourselves: what if we could take Ethereum DeFi activity and turn it into a verifiable credit score that a pawnshop in Lagos could actually use? And what if we did it with cryptographic proofs instead of just trusting some API?

That's where Sanad started.

What it does

Sanad connects three groups of people: borrowers who own gold, pawnshops who can appraise and store it, and investors who want to fund loans. The core idea is simple, prove that a borrower has good DeFi history, use that to build trust, and let real gold financing happen.

Here's the flow:

Borrower connects their wallet: Sanad discovers their DeFi activity on Ethereum, Aave repayments, Compound borrows, Morpho deposits, whatever they've done across ten supported protocols.
Proofs get built and verified on-chain: This is the part that matters. We don't just fetch data from an API and call it truth. We use Attestcoin to construct cryptographic proofs, Merkle inclusion proofs and continuity proofs and submit them to Creditcoin CC3. The SanadCreditOracle contract calls BlockProver's native verify() precompile at address 0xFD2 and only accepts evidence that passes verification.
A credit score gets calculated: Once proofs are accepted, the contract calculates a score from 0 to 1,000. The formula is:

$$S = \text{clamp}\Big(500 + 50R + \min\big(200,\; 20 \lfloor V / 100{,}000{,}000 \rfloor\big) + \min(40,\; 20B) + \min(30,\; 15C) - 40L - 150D,\; 0,\; 1000\Big)$$

where R is repayments, B is borrows, C is collateral events, L is liquidations, D is defaults, and V is total repayment volume in six-decimal USD. It's not a machine learning model, it's a transparent rule you can audit in the contract source.

Gold gets appraised and tokenized: The pawnshop inspects the gold, records karat, weight, and custody details, and mints a SAG (Sanad Asset-backed Gold) token, an ERC-721 that represents the collateral note.
Funding and repayment happen: An investor funds through InvestorVault on Sepolia, the pawnshop disburses to the borrower, and repayments flow back through RepaymentGateway. Each step generates on-chain evidence that gets proved back to Creditcoin.

The whole system runs across two networks: Creditcoin CC3 for credit scoring and collateral records, and Ethereum Sepolia for payment gateways. Attestcoin bridges the gap without actually moving funds between chains.

How we built it

We built this in layers, and honestly some of those layers were harder than we expected.

The contracts came first. We wrote the SanadCreditOracle in Solidity, which was the hardest part. It has to call BlockProver at 0xFD2, decode raw transaction calldata for ten different DeFi protocols, check that the transaction actually involves the claimed borrower, and then update a credit profile. We also built SanadLiquidityPool for cross-chain payment verification, SAGToken for the collateral NFTs, and the Sepolia gateway contracts (InvestorVault and RepaymentGateway) for routing funds.

For the proof pipeline, we built a TypeScript service in attestcoin-oracle-relayer.service.ts about 1,400 lines. It handles the full lifecycle: fetching source blocks and receipts from Ethereum RPCs, constructing proofs with the Attestcoin SDK, waiting for blocks to get attested, and submitting the encoded proofs to Creditcoin. We added retry logic with exponential backoff because proof generation isn't instant sometimes a block needs several minutes before the Attestcoin prover has cached it.

The backend is Express 5 with TypeScript, structured into 17 feature modules. Each feature, auth, credit-bureau, kyc, investor, pledge-request, loan-return, pawnshop, sag, and so on has its own routes, controllers, services, and database models. We used Drizzle ORM with PostgreSQL and Redis-backed BullMQ queues for background jobs like batch proof submission.

The credit bureau discovery engine was a research project on its own. It queries Ethereum activity, classifies transactions into protocol categories, deduplicates by hash, ranks by signal weight, and selects the top candidates. We built adapters for Aave v3, Compound v3, Morpho Blue, Spark, MakerDAO, Euler v2, Fluid, Maple Finance, Goldfinch, and Fraxlend. Each one parses different calldata layouts.

The frontend is Next.js 16 with React 19, using Tailwind, shadcn/ui components, Zustand for client state, and TanStack React Query for server data. We built separate portal views for borrowers, pawnshops, and investors. The landing page has a loan simulator, a collateral flow visualization, and a security dashboard.

The agent was the surprise. We built a Python service gold_evaluator.py that fetches live gold prices, computes risk metrics, generates rule-based explanations, and calls Ollama (running llama3.1 locally) for natural-language risk recommendations. It traces everything through OpenTelemetry to Phoenix for observability. We even added AES-256-GCM encryption for audit payloads and IPFS storage via Pinata.

The local dev environment runs on Docker Compose with PostgreSQL, Redis, Ollama, Phoenix, the backend, and the frontend all wired together. We deployed the backend to Railway and the frontend to Netlify.

Challenges we ran into

Attestcoin timing was the worst. When you submit a proof, the source block has to be attested by Attestcoin's prover first. Sometimes that takes seconds. Sometimes it takes ten minutes. We had to build a whole waitUntilHeightAttested loop with configurable timeouts and fallback retry paths. For the batch proving workflow, we group up to 10 events and share one continuity proof but if the attestation is delayed, the whole batch stalls.

Calldata decoding is a minefield. We initially thought we could parse Aave's repay() calldata and call it a clean repayment event. Turns out Compound supply can look like repayment, Maker operations can go in either direction, and Euler batches can pack multiple internal actions into one transaction. We got it working for the ten protocols we support, but the white paper is honest about it, our decoding is defensive heuristics, not production-grade semantic parsing.

Two-chain architecture creates accounting headaches. We keep saying "credit separation", proven facts on Creditcoin, actual funds on Sepolia but making that clean in practice was hard. A proven Sepolia payment is not withdrawable CTC. The pool contract tracks ETH balances and CTC balances separately, and we had to be really careful that cross-chain funding evidence didn't accidentally get treated as native liquidity.

The scoring formula went through five versions. We started with a 300–850 range like FICO, but it didn't map well to the DeFi signals we were seeing. A borrower with three repayments and no liquidations should score differently than someone with the same number of borrows but no repayment history. We landed on the 0–1,000 range with the formula above, which is simple enough to audit on-chain and directional enough to be useful.

Accomplishments that we're proud of

We have a real proof on-chain. Not a mock, not a demo, an actual Attestcoin proof submitted to Creditcoin CC3 that you can inspect. Block 5,440,388, call selector 0x584194a4 matching submitSingleProof(), events EventProven and CreditScoreUpdated, score moved from 675 to 695. The source Sepolia transaction is also public. That's the kind of reproducibility we wanted.

The credit bureau actually works across ten protocols. We built adapters for Aave, Compound, Morpho, Spark, MakerDAO, Euler, Fluid, Maple, Goldfinch, and Fraxlend. The discovery engine deduplicates, ranks, and selects candidates. The oracle verifies them on-chain. That's not a toy integration.

We kept the contracts honest. The white paper explicitly lists what we didn't do: we don't bridge liquidity, we don't attest physical gold, we don't claim the scoring is calibrated. The credit separation principle is baked into the code. Cross-chain proven capital doesn't become withdrawable CTC. That discipline is rare in hackathon projects.

The full stack runs locally. Docker Compose brings up Postgres, Redis, Ollama, Phoenix, the backend, and the frontend. You can clone the repo, run docker compose up, and have the whole system working. That matters for reproducibility.

We have real equations, not hand-waves. The credit score formula, the custody fee calculation, the Dutch auction liquidation price — they're all in the contracts and the white paper. You can check the math:

$$U(t) = \lfloor M \cdot \max(0,\; t_{\text{end}} - t_{\text{origin}}) / (30 \times 24 \times 60 \times 60) \rfloor$$

for custody fees, and

$$P(t) = P_{\text{start}} - (P_{\text{start}} - P_{\text{reserve}}) \cdot \min!\left(\frac{t - t_{\text{start}}}{T},\; 1\right)$$

for the descending Dutch auction. Transparent, auditable, on-chain.

What we learned

Proofs are not data. The biggest thing. An API that says "this person repaid a loan" is a claim. An Attestcoin proof that passes BlockProver verification is a cryptographic fact. They're not the same thing, and the entire architecture has to respect that difference. That's why Sanad checks proofs inside the Solidity contracts instead of just trusting a backend.

Physical custody is the real bottleneck. We can build the best credit scoring system in the world, but someone still has to physically appraise gold, verify karat, and store it safely. That's a pawnshop's job, not a smart contract's job. Sanad deliberately separates verification from custody, and that was the right call.

Islamic finance needs better infrastructure, not just better products. The math for Shariah-compliant financing is well-defined Ujrah for custody fees, Rahn for collateral, Mudarabah for profit-sharing. But the tooling to actually implement these on-chain is barely there. We learned that building the infrastructure layer is where the real work is.

What's next for Sanad Protocol

Stage 1: Harden what we have. The credit oracle's claim validation needs explicit receipt-success checks on-chain. The calldata decoding needs to bind canonical identity more rigorously. The schema and address registry need unification. We need to remove stale documentation and distinguish fixtures from live data. None of this is glamorous, but it's the difference between a demo and a system.

Stage 2: Escrow-based settlement. Right now, funding flows from investor to pawnshop, then pawnshop to borrower. That's two trust assumptions. The redesign puts both paths through an escrow with explicit release conditions — borrower repayment enters a contract that handles investor and custody-fee entitlements automatically. No more "pawnshop sends a second payment after receiving borrower funds."

Stage 3: Attestcoin writability. When Attestcoin supports authenticated cross-chain instructions, Sanad should be ready. The first demonstration should be narrow: prove a repayment, authorize a distribution from escrow, execute on Sepolia, confirm on Creditcoin. Failed callbacks, relayer downtime, and delayed acknowledgements all need visible recovery states. No premature "settled" badges.

We also want to explore publishing issuer-authenticated credit tiers to an external chain — a credit-registry adapter that lending protocols could actually integrate. And multi-chain collateral recognition, which requires preventing duplicate pledges across networks.

But honestly, the immediate next step is just making what we built more robust. Sanad is a testnet prototype. The proof pipeline works, the credit scoring works, the gold financing workflow works. Now it needs the hardening that turns a hackathon project into infrastructure people can actually build on.