Skip to content

update #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hosein-ul merged 6 commits into from
Jul 7, 2026
Merged

update #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6c0087f
fix: replace ampersands in setup.ps1 comments with 'and' to fix irm |…
hosein-ul Jul 6, 2026
18fabdc
update readme.md
hosein-ul Jul 6, 2026
77dcf02
Clarify handling of confidential tokens in README
hosein-ul Jul 7, 2026
509639a
feat: improve error handling, add modern token selector & visual deco…
hosein-ul Jul 7, 2026
45c4f0b
docs: add decrypt signature behavior FAQ to README
hosein-ul Jul 7, 2026
567c5fe
feat: add transparent logo, dark mode support for landing page, and r…
hosein-ul Jul 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .agents/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Universal Anti-Hallucination & Verification Protocol (MANDATORY FOR ALL AGENTS)

## 1. Zero-Hallucination Policy & Strict Verification (Universal Scope)
- **Universal Applicability:** This protocol applies universally to ALL technologies, domains, and tools — including **MCP (Model Context Protocol) servers/tools**, smart contracts, blockchain SDKs (e.g., Zama, Circle, Viem), UI frameworks (e.g., shadcn, Next.js, Tailwind), cloud APIs, databases, and system architectures.
- **Never Assume or Guess:** Do NOT invent, guess, or hallucinate function signatures, MCP tool parameters, contract ABIs, addresses, API endpoints, CSS classes, or configuration headers from training data memory.
- **Read Authoritative Sources FIRST:** Before calling any tool, writing code, or generating documentation, you MUST explicitly read and verify ground-truth sources:
1. **MCP Servers & Tools:** Before calling lazy-loaded MCP tools or using MCP resources, always read their schema definitions (`<toolName>.json`), check available tools/resources (`list_resources`, `read_resource`), and review server instructions (`instructions.md`).
2. **Local Codebase & ABIs:** Inspect existing files (e.g., ABI files, types, interfaces, utility wrappers) to verify exact names, types, and signatures in use.
3. **Installed Dependencies & Skills:** When integrating third-party SDKs or frameworks, inspect `node_modules` or read local skill instructions (`SKILL.md`) and reference docs (`references/`) before implementing domain logic.

## 2. Mandatory "Think -> Read -> Plan -> Execute" Workflow
Before executing any coding, configuration, or integration task across any technology stack:
1. **Think & Analyze:** Identify exact information needed (e.g., MCP tool schemas, API parameters, contract addresses, decimal scaling rules).
2. **Read & Verify:** Use read tools (`view_file`, `grep_search`, `read_resource`, `call_mcp_tool`) to verify 100% accurate data from ground-truth sources.
3. **Plan:** Outline exact changes or tool invocations, confirming that every name, parameter, and address matches verified sources without guessing.
4. **Execute & Audit:** Apply changes and double-check against ground truth to ensure zero discrepancies, syntax errors, or placeholder values remain.

## 3. Strict Prohibitions
- **No Hallucinated MCP / Tool Calls:** Never call MCP tools or agent skills with guessed arguments; always verify parameter schemas first.
- **No Unauthorized Architectural / Security Changes:** Never add custom headers (like COOP/COEP/CORP), security policies, or infrastructure overrides without explicit user authorization or documented vendor requirements.
- **No Placeholder Leakage:** Never put fake placeholder addresses (e.g., `0x1000...`), mock ABIs, or fake API keys into production code, SDKs, or LLM reference manifests (`llms.txt`, `llms-full.txt`, `agent-tools.ts`). Always use verified ground-truth values.
52 changes: 45 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,17 @@
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

ShadowLine is an enterprise-grade, non-custodial decentralized application (dApp) that acts as the primary gateway for Zama's FHEVM Wrappers Registry. Built entirely on Fully Homomorphic Encryption (FHE), ShadowLine enables users and institutions to seamlessly shield standard ERC-20 tokens into ERC-7984 confidential tokens (cTokens) and perform private on-chain asset transfers.
ShadowLine is a non-custodial dApp built on top of Zama's Confidential
Token Wrappers Registry, powered by Zama's FHEVM. It lets you shield
ERC-20 tokens into ERC-7984 confidential tokens (cTokens), unshield them
back, and send confidential transfers with encrypted amounts.

Beyond wrapping, ShadowLine includes user decryption of your own balances,
a browsable token registry with custom-token support, a portfolio view,
and a testnet faucet — across Sepolia and coming soon on Ethereum mainnet.

Because balances and transfer amounts are handled as ERC-7984 confidential tokens, they stay encrypted on-chain and are computed in their encrypted state via FHE. Wallet addresses remain public on-chain, as with any standard transaction.

With ShadowLine, transaction amounts and token balances remain completely encrypted on the blockchain, computable only in their encrypted state, while sender and receiver identities are preserved for ledger auditing.

---

Expand All @@ -26,13 +34,16 @@ With ShadowLine, transaction amounts and token balances remain completely encryp
- [8. How to Configure a New Token Pair](#8-how-to-configure-a-new-token-pair)
- [9. Local Development & Setup](#9-local-development--setup)
- [10. Repository Structure](#10-repository-structure)
- [11. License](#11-license)
- [11. Zama SDK 3.0.1 — methods used](#11-zama-sdk-301--methods-used)
- [12. FAQ: Why doesn't Decrypt ask for signature on some tokens?](#12-faq-why-doesnt-decrypt-ask-for-signature-on-some-tokens)
- [13. License](#13-license)

---


## 1. About ShadowLine

Traditional blockchain networks expose all transaction values and account balances to public block explorers, posing significant security and privacy risks for both retail users and commercial enterprises. ShadowLine addresses this challenge by utilizing Torus Fully Homomorphic Encryption (TFHE) on-chain via Zama's FHEVM.
Traditional blockchain networks expose all transaction values and account balances to public block explorers, posing significant security and privacy risks for both retail users and commercial enterprises. ShadowLine addresses this challenge by using Fully Homomorphic Encryption (FHE) on-chain via Zama's FHEVM.

It wraps public ERC-20 tokens into **ERC-7984 Confidential Wrappers** (cTokens), converting open balance data into cryptographic ciphertext handles (`euint64`). Transactions and balances are processed on-chain in their encrypted state, ensuring confidentiality while maintaining decentralized validation.

Expand All @@ -51,6 +62,7 @@ ShadowLine supports the following network configurations:

---


## 3. Core Features Deep Dive

ShadowLine is divided into specialized modules tailored for retail and enterprise confidentiality management:
Expand Down Expand Up @@ -101,6 +113,7 @@ An in-app documentation portal explaining technical architecture, decimal scalin

---


## 4. Technical Architecture & Data Flows

ShadowLine's architecture decouples public blockchain logic, local cryptographic calculations, and decentralized key management:
Expand Down Expand Up @@ -137,6 +150,7 @@ ShadowLine's architecture decouples public blockchain logic, local cryptographic
└──────────────────────┘
```


### 4.1 FHE Shielding Flow (Public to Confidential)

The diagram below illustrates the process of shielding public ERC-20 tokens into encrypted cTokens:
Expand All @@ -162,6 +176,7 @@ sequenceDiagram
Wrap-->>User: Tx Confirmed (Shield Completed)
```


### 4.2 FHE Decryption Flow (Confidential to Plaintext)

To query and view confidential balances, ShadowLine uses EIP-712 permits. The process prevents gas consumption and ensures the plaintext is only visible to the user:
Expand All @@ -187,8 +202,10 @@ sequenceDiagram
SDK->>User: Display Plaintext Balance (e.g., 1,000 cUSDT)
```


---


## 5. Security & Cryptographic Trust Model

ShadowLine's privacy architecture relies on the following security properties:
Expand All @@ -198,8 +215,10 @@ ShadowLine's privacy architecture relies on the following security properties:
* **EIP-712 Permit Scoping:** Permit signatures are read-only and restricted to balance views. They cannot approve token transfers, withdraw funds, or modify contract states.
* **Zero-Knowledge KMS Boundaries:** The Key Management System (KMS) re-encrypts FHE ciphertexts from the network key to the user's session key. This cryptographic handshake ensures that neither the KMS gateway nor any relayer can inspect the user's plaintext values.


---


## 6. Hybrid Registry Sourcing Strategy

To guarantee uptime and developer flexibility, ShadowLine merges token information from three layers:
Expand All @@ -225,6 +244,7 @@ To guarantee uptime and developer flexibility, ShadowLine merges token informati

---


## 7. B2B & Enterprise Use Cases

Confidential ERC-7984 wrapper standard implementations enable several corporate use cases:
Expand All @@ -235,11 +255,13 @@ Confidential ERC-7984 wrapper standard implementations enable several corporate

---


## 8. How to Configure a New Token Pair

Two paths, no on-chain governance required. Both flow the pair through the exact same shield / unshield / decrypt code paths as an Official registry pair — the only difference is which section lists it (**Official — Zama Registry** vs **Custom / Dev-only Tokens**).

The on-chain Wrappers Registry is owned by the Zama Protocol DAO — calling `registerPair` from ShadowLine reverts. So ShadowLine declares custom pairs **locally**: either seeded in the repo (path A, ships with the app) or added at runtime in the browser (path B, per-user).
The on-chain Wrappers Registry is permissioned and not publicly writable — its `registerConfidentialToken(erc20, wrapper)` entrypoint cannot be called by ShadowLine. So ShadowLine declares custom pairs **locally**: either seeded in the repo (path A, ships with the app) or added at runtime in the browser (path B, per-user).


Resolution order at read time: **on-chain registry (primary) → `CUSTOM_PAIRS` config → browser localStorage → hardcoded offline snapshot**. On-chain always wins on any address conflict.

Expand Down Expand Up @@ -270,6 +292,7 @@ export const CUSTOM_PAIRS: CustomPair[] = [

**Requirement:** `erc7984Address` must implement ERC-165 and return `true` for interface id `0x4958f2a4`. If it doesn't, ShadowLine's Add-Custom-Pair form rejects it — see path B.


### Path B — Add a pair from the UI (persists only in this browser)

**Step 1:** Open the dApp at `/app` and connect a wallet on the target network (Sepolia or Mainnet). The wallet is used for chain resolution — validation itself runs against a public RPC and doesn't require a signature.
Expand Down Expand Up @@ -305,8 +328,10 @@ Sepolia's on-chain registry contains a second, non-mintable `tGBP` wrapper deplo

To demonstrate the *success* path, deploy any ERC-7984 wrapper of your own on Sepolia, paste that wrapper address, and click **Add Pair** — the row will appear under **Custom / Dev-only Tokens** and route through the same shield/unshield/decrypt code paths as any official pair.


---


## 9. Local Development & Setup (0-to-100 DevOps Suite)

Want to run ShadowLine locally or deploy to a cloud node / VPS in under 1 minute? We built an automated, zero-friction **0-to-100 DevOps Wizard** that handles prerequisite checking (Git, Node.js v18+), environment configuration (`.env.local`), production build verification, and server launching.
Expand Down Expand Up @@ -370,10 +395,11 @@ npm run start
```
Open `http://localhost:3000` to interact with the application.

**Live URL:** https://shadow-line.netlify.app/
**Live URL:** https://shadow-line.vercel.app/

---


## 10. Repository Structure

```
Expand Down Expand Up @@ -404,6 +430,7 @@ src/

---


## 11. Zama SDK 3.0.1 — methods used

ShadowLine is pinned to `@zama-fhe/sdk` + `@zama-fhe/react-sdk` **3.0.1** (verified against installed `.d.ts`, which is treated as ground truth over the docs site). The build uses only what exists in that release:
Expand All @@ -424,6 +451,17 @@ ShadowLine is pinned to `@zama-fhe/sdk` + `@zama-fhe/react-sdk` **3.0.1** (verif

---

## 12. License
## 12. FAQ: Why doesn't Decrypt ask for signature on some tokens?

There are two legitimate reasons why the Decrypt action might not prompt you for a wallet signature:

1. **No balance yet** — If you've never received or wrapped this token, its confidential balance handle on-chain is `bytes32(0)`. The SDK recognizes this and returns `0` instantly without needing to sign or contact the relayer. There's no ciphertext to decrypt.
2. **Cached credentials** — After you sign once (via `useAllow`), an EIP-712 permit is stored in IndexedDB for up to 30 days. Any subsequent decrypt for a contract covered by that permit reuses the cached credential and skips the signature prompt.

Both behaviors follow Zama's official SDK guidance.

---

## 13. License

This project is licensed under the **MIT License**. See the `LICENSE` file for details.
Loading
Loading