Privacy Architecture

Privacy by Design

Walnut leverages Fully Homomorphic Encryption (FHE) to ensure your financial data remains confidential. We don't just protect your privacy; we mathematically guarantee it.

100%

Encrypted Operations

FHE Primitives

Plaintext Exposure

System Architecture

Three-Layer
Confidential Stack

Walnut's architecture ensures that sensitive financial data never exists in plaintext on-chain, while maintaining full protocol functionality through encrypted computation.

Client-Side Encryption

All sensitive values encrypted before leaving user's wallet using Fhenix SDK

fhenixjsInEuint128Permit Signatures

FHE Computation Layer

Smart contracts execute operations on encrypted data without decryption

FHE.addFHE.subFHE.mulFHE.divFHE.select

Client-Driven Decryption Sync

Selective decryption verified via secure enclave ECDSA signatures

verifyDecryptResultSafeEnclave SignaturesOff-chain Sync

FHE Operations

Encrypted
Computation Primitives

Walnut leverages Fhenix's FHE library to perform arithmetic and logical operations directly on encrypted data without ever exposing plaintext values.

FHE.add

euint128

Homomorphic addition on encrypted integers

Use case: Aggregate collateral across wallets

WalnutProtocol.sol

FHE

euint128 total = FHE.add(
  userCollateral[wallet1],
  userCollateral[wallet2]
);

FHE.sub

euint128

Homomorphic subtraction for balance updates

Use case: Decrement debt on repayment

WalnutProtocol.sol

FHE

userDebt[msg.sender] = FHE.sub(
  userDebt[msg.sender],
  encryptedAmount
);

FHE.mul

euint128

Encrypted multiplication for interest calculations

Use case: Compute accrued interest

WalnutProtocol.sol

FHE

euint128 interest = FHE.mul(
  principal,
  encryptedRate
);

FHE.div

euint128

Homomorphic division for ratio computation

Use case: Calculate health factor

WalnutProtocol.sol

FHE

euint128 healthFactor = FHE.div(
  totalCollateral,
  totalDebt
);

FHE.select

euint128

Conditional selection in ciphertext

Use case: Find minimum bid in sealed auction

WalnutProtocol.sol

FHE

euint128 minBid = FHE.select(
  FHE.lt(bid1, bid2),
  bid1,
  bid2
);

FHE.allowPublic

euint128

Grant decryption permissions to public enclaves

Use case: Authorize secure client-driven decryption

WalnutProtocol.sol

FHE

FHE.allowPublic(mintedAmount);
uint256 ctHash = uint256(
  euint128.unwrap(mintedAmount)
);

Execution Flow

End-to-End
Encrypted Execution

From client-side encryption to on-chain storage, sensitive data never exists in plaintext.

Client Encryption

Plaintext → Ciphertext

User encrypts borrow amount using fhenixjs before transaction request

client.ts

Client

const encrypted = await fhenixClient.encrypt_uint128(
  borrowAmount
);

await walnut.borrow(encrypted);

On-Chain FHE Computation

Ciphertext → Ciphertext

Contract performs LTV check and updates encrypted balances without decryption

WalnutProtocol.sol

Contract

// Compute encrypted health factor
euint128 hf = FHE.div(collateral, debt);

// Update encrypted debt
userDebt[msg.sender] = FHE.add(
  userDebt[msg.sender],
  encryptedAmount
);

Encrypted State Persisted

Ciphertext Storage

All sensitive values remain encrypted in contract storage. No plaintext exposure.

storage.sol

Storage

// Storage layout
mapping(address => euint128) userCollateral;
mapping(address => euint128) userDebt;
mapping(address => euint128) repaymentCount;

Storage Architecture

Encrypted State
Management

All sensitive protocol state is stored as encrypted integers (euint128). No plaintext financial data ever touches contract storage.

Encrypted Storage Layout

Core protocol state stored as FHE-encrypted integers

WalnutStorage.sol

Storage

// User positions
mapping(address => euint128) userCollateral;
mapping(address => euint128) userDebt;
mapping(address => euint128) repaymentCount;

// Pool state
euint128 totalPoolCollateral;
euint128 totalPoolDebt;

// P2P offers
struct Offer {
  euint128 apr;
  euint128 size;
  euint128 tenor;
  bool active;
}
mapping(uint256 => Offer) offers;

// Liquidation bids
mapping(address => euint128[]) bids;

Permit-Based Access Control

Users grant read permissions via FHE.allow for selective decryption

WalnutPermit.sol

ACL

// Grant contract permission
FHE.allowThis(userCollateral[msg.sender]);
FHE.allowThis(userDebt[msg.sender]);

// Grant specific address permission
FHE.allow(
  offers[offerId].apr,
  borrower
);

// P2P: only lender and borrower can read
FHE.allow(encryptedTerms, lender);
FHE.allow(encryptedTerms, borrower);

// Third parties: no access

No Plaintext Storage

All sensitive values stored as euint128 ciphertexts

Granular Permissions

Users control who can decrypt their encrypted data

Composable Privacy

Encrypted state can be used in other FHE operations

Client-Driven Decryption Sync

Selective Decryption
Through Enclave Verification

When protocol logic requires a plaintext value, Walnut coordinates decryption off-chain and validates ECDSA enclave signatures on-chain. Decrypted values exist only during transaction execution — never stored, never emitted in logs.

syncPositionGuardCheck

Trigger: Health factor decryption

signature-verified

Set liquidatable flag based on decrypted health factor

WalnutLending.sol

ECDSA Verify

function syncPositionGuardCheck(
  euint128 ciphertext,
  uint128 result,
  bytes calldata signature
) external {
  require(
    FHE.verifyDecryptResultSafe(ciphertext, result, signature),
    "Invalid signature"
  );
  
  address user = ciphertextToUser[ciphertext];
  if (result == 1) {
    isLiquidatable[user] = true;
    emit LiquidationEligible(user);
  }
}

syncWinnerSelected

Trigger: Minimum bid index decryption

signature-verified

Reveal winning liquidator without exposing bid amounts

WalnutLending.sol

ECDSA Verify

function syncWinnerSelected(
  euint128 ciphertext,
  uint128 winnerIndex,
  bytes calldata signature
) external {
  require(
    FHE.verifyDecryptResultSafe(ciphertext, winnerIndex, signature),
    "Invalid signature"
  );
  
  address user = auctionUser[ciphertext];
  address winner = bidders[user][winnerIndex];
  
  // Execute liquidation with winner
  _executeLiquidation(user, winner);
}

syncCreditCount

Trigger: Repayment count decryption

signature-verified

Map encrypted count to public credit tier

WalnutLending.sol

ECDSA Verify

function syncCreditCount(
  euint128 ciphertext,
  uint128 count,
  bytes calldata signature
) external {
  require(
    FHE.verifyDecryptResultSafe(ciphertext, count, signature),
    "Invalid signature"
  );
  
  address user = ciphertextToUser[ciphertext];
  uint8 tier = _computeTier(count);
  creditTier[user] = tier;
  
  emit CreditTierUpdated(user, tier);
}

ECDSA Enclave Verification Principle

All client-driven sync actions are verified using the verifyDecryptResultSafe function on-chain, which validates that the decrypted value matches a valid ECDSA signature signed directly by FHE enclave nodes. Decrypted values exist solely in transaction execution scope and are never persisted to storage or emitted in events, ensuring maximum security and zero leak potential through indexers or chain history.

Confidential Use Cases

Privacy-Preserving
Lending Primitives

Walnut's FHE architecture enables lending features that are structurally impossible in traditional transparent DeFi.

Sealed-Bid Liquidations

Traditional DeFi Problem

Traditional DeFi: liquidation bids are public, enabling MEV extraction and unfair outcomes

Walnut Solution

Walnut: liquidators submit encrypted bids. FHE.select finds minimum in ciphertext. Only winner revealed.

Privacy Guarantees

Bid amounts encrypted forever

No MEV visibility

Borrowers get best outcome

FHE.selectEncrypted auctionEnclave-signed sync

Private Credit Scoring

Traditional DeFi Problem

On-chain credit history is fully public, exposing user financial behavior to everyone

Walnut Solution

Walnut: repayment count stored as euint128. CoFHE decrypts privately to compute tier. Only tier is public.

Privacy Guarantees

Repayment history encrypted

Count never public

Tier-based LTV unlocks

euint128 counterPrivate tier mappingSelective disclosure

Confidential P2P Terms

Traditional DeFi Problem

Loan terms (APR, size, duration) are visible to all participants and indexers

Walnut Solution

Walnut: lender encrypts terms. Only matched borrower gets FHE.allow permission. Third parties see nothing.

Privacy Guarantees

APR stays private

Loan size encrypted

Duration confidential

FHE.allowPermit-based accessEncrypted offers

ENS Wallet Aggregation

Traditional DeFi Problem

Linking wallets publicly reveals user's full portfolio and relationships

Walnut Solution

Walnut: aggregate encrypted collateral across wallets using FHE.add. No public wallet linking.

Privacy Guarantees

Wallet relationships hidden

Aggregated balance private

Higher LTV without exposure

FHE.addENS identityCross-wallet privacy

Technical Specifications

Infrastructure
Details

System Specifications

Encryption SchemeFully Homomorphic Encryption (FHE)

FHE ProviderFhenix CoFHE

Encrypted Typeeuint128

NetworkArbitrum Sepolia (Testnet)

Verification SystemClient-Driven Decryption Sync

Access ControlPermit-based (FHE.allow)

Storage ModelEncrypted-by-default

Plaintext ExposureTransaction-execution scope only

Developer Resources

GitHub Repository Fhenix Documentation CoFHE Architecture FHE Primitives

Experience Confidential Lending

Walnut Protocol is live on Arbitrum Sepolia testnet. Try encrypted borrowing, sealed-bid liquidations, and private credit scoring.

Launch App View on GitHub

Privacy by Design

Three-LayerConfidential Stack

Client-Side EncryptionClient-Side Encryption

FHE Computation LayerFHE Computation Layer

Client-Driven Decryption SyncClient-Driven Decryption Sync

EncryptedComputation Primitives

FHE.add

FHE.sub

FHE.mul

FHE.div

FHE.select

FHE.allowPublic

End-to-EndEncrypted Execution

Client Encryption

On-Chain FHE Computation

Encrypted State Persisted

Encrypted StateManagement

Encrypted Storage Layout

Permit-Based Access Control

No Plaintext Storage

Granular Permissions

Composable Privacy

Selective DecryptionThrough Enclave Verification

syncPositionGuardCheck

syncWinnerSelected

syncCreditCount

ECDSA Enclave Verification Principle

Privacy-PreservingLending Primitives

Sealed-Bid Liquidations

Private Credit Scoring

Confidential P2P Terms

ENS Wallet Aggregation

InfrastructureDetails

System Specifications

Developer Resources

Experience Confidential Lending

Three-Layer
Confidential Stack

Client-Side Encryption

FHE Computation Layer

Client-Driven Decryption Sync

Encrypted
Computation Primitives

End-to-End
Encrypted Execution

Encrypted State
Management

Selective Decryption
Through Enclave Verification

Privacy-Preserving
Lending Primitives

Infrastructure
Details