> For the complete documentation index, see [llms.txt](https://plabs.gitbook.io/plabs-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plabs.gitbook.io/plabs-docs/privacy-core/shield-erc20/overview.md).

# Overview

**Shield ERC20** privatizes **existing public ERC-20** tokens. It is an **asset protocol** under Privacy Core (alongside [pERC20](/plabs-docs/privacy-core/perc20/overview.md)), not a swap/payment application.

## One line

> Deposit a standard ERC-20 into custody → receive **private notes** backed 1:1; spend notes → **unshield** releases underlying to a bound recipient.

## Contract structure

```solidity
contract ERC20Shield is OrchardVerifier, IERC20Shield
```

| Inheritance                    | Provides                                                        |
| ------------------------------ | --------------------------------------------------------------- |
| `OrchardVerifier`              | Privacy Core state machine                                      |
| `IERC20Shield`                 | Custody metadata, `shield` / `unshield`, disabled `mint`/`burn` |
| `IPERC20` (via `IERC20Shield`) | Metadata, `totalSupply`, `transfer`, compliance freeze          |

## pERC20 vs Shield ERC20

|                        | **pERC20 (`PERC20`)**               | **Shield ERC20 (`ERC20Shield`)**               |
| ---------------------- | ----------------------------------- | ---------------------------------------------- |
| Value source           | Issuer `mint` / holder `burn`       | User `shield` / `unshield`                     |
| External custody       | None (`totalSupply` is bookkeeping) | Yes — pool locks underlying ERC-20             |
| Permissionless deposit | No (`onlyIssuer` mint)              | Yes — anyone may `shield`                      |
| Supply cap             | Issuer policy                       | Pool's custodied balance                       |
| `mint` / `burn`        | Enabled                             | **Disabled** (`MintDisabled` / `BurnDisabled`) |
| Typical use            | Privacy-native issuance             | Privatize USDC, WETH, etc.                     |

Cryptographically, **`mint` is shield without custody** and **`burn` is unshield without payout**. `ERC20Shield` adds the ERC-20 pull/transfer layer and enforces the custody invariant.

## Stack position

```
Shield ERC20  →  deposit / withdraw rules, ERC-20 custody, scale
       │
pERC20 / OrchardVerifier  →  shielded note state machine (shared Groth16 VK)
```

Built on the same [Privacy Core](/plabs-docs/privacy-core/overview.md) primitives as [pERC20](/plabs-docs/privacy-core/perc20/overview.md). Shield pools share the same circuit, verifier, and note format — they are **swap-compatible** with issuer-minted pERC20 assets via value-neutral `transfer`.

## Custody invariant

Every unit of shielded supply must be matched by custodied underlying:

```
underlying.balanceOf(pool) >= shieldedSupply * scale
```

* `shield` increases both sides by `amountUnits * scale`
* `unshield` decreases both sides by `amountUnits * scale`
* `transfer` is value-neutral — touches neither custody nor `shieldedSupply`

`>=` (not `==`) allows direct donations to the pool; excess underlying cannot be claimed by any note.

## Units

| Term                 | Meaning                                                            |
| -------------------- | ------------------------------------------------------------------ |
| **Note unit**        | Value field inside a shielded note (64-bit circuit range)          |
| **`scale`**          | Wei of underlying per note unit: `weiAmount = amountUnits * scale` |
| **`shieldedSupply`** | Total backed note units (also exposed as `totalSupply()`)          |

Dust below one note unit (`< scale` wei) cannot be shielded.

## Implementation

| Contract  | Path                                      |
| --------- | ----------------------------------------- |
| Pool      | `contracts/ptoken/ERC20Shield.sol`        |
| Factory   | `contracts/ptoken/ERC20ShieldFactory.sol` |
| Interface | `contracts/interfaces/IERC20Shield.sol`   |

## Next

* [Interface & pERC20 mapping](/plabs-docs/privacy-core/shield-erc20/interface-and-perc20.md)
* [Operations: shield / unshield / transfer](/plabs-docs/privacy-core/shield-erc20/operations.md)
* [Deployment & factory](/plabs-docs/privacy-core/shield-erc20/deployment.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://plabs.gitbook.io/plabs-docs/privacy-core/shield-erc20/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.