Architecture

A technical deep dive into how Veil Protocol assembles Midnight ZK proofs, CKB identity anchors, and a multi-chain behavioral data layer into a coherent privacy-preserving credit system.

Cross-Chain Credit Scoring

Credit scoring in traditional finance relies on centralized data aggregators (credit bureaus) that collect repayment histories from lenders, normalize the data, and issue a score. This works because identity is anchored to government IDs and social security numbers — persistent identifiers that lenders trust.

In decentralized finance, wallets are pseudonymous by design. There is no persistent identifier across chains, no credit bureau, and no way to aggregate behavioral data across Ethereum, Solana, and Polygon for the same user without either linking wallet addresses (destroying privacy) or relying on off-chain identity systems (recreating the surveillance infrastructure of traditional finance).

Traditional vs. DeFi Credit

Veil's breakthrough is the use of a pseudonymous identity hash (the veilIdHash) as the cross-chain aggregation key, combined with ZK proofs that certify score properties without revealing the score itself. TheveilIdHashis derived from the user's Midnight public key, which is cryptographically bound to their identity but never linked to their other-chain wallets unless the user explicitly discloses that link.

The Three Roles

The Veil Protocol ecosystem has three distinct participant roles, each with different interactions and trust relationships:

ZK Proof Pipeline

The zero-knowledge proof pipeline is the technical core of Veil's privacy guarantees. Here is a complete walkthrough of what happens from score computation to on-chain commitment:

The Compact Contract

The Veil smart contract is written in Compact — Midnight's ZK-native smart contract language. Compact programs are compiled into two artifacts:

• A ZK circuitthat encodes the computation the prover must perform. For Veil, the circuits validate issuer authorization, update private score accumulators, maintain score commitments, and derive the user's deterministic Veil ID without exposing the user's secret key.
• A ledger program that manages on-chain state: the mapping of public issuer/admin state, replay-protection sets, and Merkle commitments to private score and accumulator records.

The Compact contract exposes the following operations:

• Utils_generateUserPk(secret) — Derive the user's deterministic Veil ID locally.
• Scoring_createScoreEntry(userPk) — Create an empty private score and accumulator entry.
• Scoring_submitRepaymentEvent, Scoring_submitLiquidationEvent, Scoring_submitProtocolUsageEvent, and Scoring_submitDebtStateEvent — Record issuer-submitted behavioral events.
• Admin_addIssuer and related admin circuits — Manage approved data issuers and score policy.

Proof Generation

When a scoring event is submitted, the following happens inside the Midnight proof and transaction flow:

1. The witness provides the current private score/accumulator record and the Merkle path proving the existing commitment is part of the Midnight ledger state.
2. The ZK circuit validates the issuer, rejects duplicate/backdated events, updates the accumulator, and creates a new commitment.
3. The prover outputs a transaction proof showing the state transition is valid without revealing the private accumulator contents.
4. The on-chain contract verifies the proof and stores only the updated public commitment and replay-protection data.

The key property is that public observers see commitments and authorized decision outputs, not raw score values or behavioral records.

CKB Identity Layer

The CKB layer solves a specific problem: how do multiple parties verify that theveilIdHash in a credit decision belongs to the same entity as a specific CKB wallet address, without relying on Veil as a trusted intermediary?

The answer is the Spore DOB. When a user mints a DOB, they:

1. Sign the CKB transaction with their CKB private key, proving ownership of theownerCkbLockHash.
2. Embed the veilIdHash in the DOB content, which is stored on-chain and publicly readable.
3. The DOB is then a self-certifying, immutable claim: "The owner of this CKB lock hash is associated with this veilIdHash."

Any protocol can verify this claim by querying the CKB blockchain for DOBs with the given veilIdHashand checking that the DOB's lock matches the user's claimed CKB address. No trust in Veil or any other party is required.

Privacy Model

What Is Never Revealed

The following information is explicitly protected by the Veil privacy model:

• Raw credit score:The numeric score is stored only in Midnight private state. It is private input to Veil's scoring flow and is never included in any public transaction or API response.
• Wallet addresses on other chains: The veilIdHashis a one-way hash. Knowing the hash does not reveal the user's Ethereum, Solana, or other wallet addresses.
• Specific behavioral events:Individual events (e.g. "repaid loan on Aave on March 15") are never published publicly. The behavioral data is aggregated into the score computation and then discarded from public-facing storage.
• Score history: Public data exposes commitments and fresh decision outputs, not the full score trajectory.

What Is Publicly Verifiable

The following information is intentionally public and verifiable:

• Current credit band: The band (Unranked, Bronze, Silver, Gold, Platinum) is returned by the credit decision API after DOB and wallet-signature verification. This is the minimum necessary for a lending protocol to make a credit decision.
• Decision validity: The timestamp (validAt) is public so protocols can verify the decision is fresh.
• DOB existence on CKB: The Spore DOB is a public CKB cell. Any party can verify that a veilIdHash has a corresponding DOB on CKB.
• Protocol participation: The fact that a user has joined the Veil contract and created a score entry is on-chain on Midnight (but without linking to their other-chain identity).

Trust Assumptions

No system is trustless. Veil's trust assumptions are:

The strongest trust assumption is in the Veil backend oracle — it currently holds the exclusive ability to submit behavioral events and compute scores. Future iterations of the protocol aim to introduce a decentralized oracle network so that no single entity controls the score computation.