# Shield developer guide

Current implementation and deployment workflow · 2 October 2026

Shield is a privacy pool for **BNB Smart Chain**: mainnet `56` and testnet `97`.
The initial assets are BNB, USDT and USDC. Ethereum and cross-chain transfers are not supported.

## Current status

The contracts, circuit, browser SDK, relayer/indexer and admin deployment flow are implemented.
They have been exercised on a local fork of BNB Smart Chain, but **Shield has not been deployed on a public network**.
The app's demo uses sample balances and does not transfer real funds.
Two internal adversarial reviews have been completed; a third-party audit is still pending.
Use the repository's `AGENTS.md`, `LAUNCH.md` and `protocol/SECURITY_REVIEW.md` for maintenance rules, launch steps and security findings.

## What each transaction does

| Action | Behavior | Public information |
| --- | --- | --- |
| Shield | Deposit native BNB or a supported token and create an encrypted note in the pool. | Depositor address, token, amount and transaction timing. |
| Send | Spend notes and create recipient/change notes for Shield addresses. The browser generates a Groth16 proof. | Pool activity, token, commitments, nullifiers, gas payer and timing. |
| Swap | Spend notes through the approved PancakeSwap V2 adapter and receive the output in a shielded note. | DEX calls, token pair, amounts, route and timing. |
| Withdraw | Spend notes and release funds to a public BNB Smart Chain address. | Recipient, token, amount, fees and timing. |

Zero-knowledge proofs do not guarantee anonymity. Amounts, timing, wallet reuse, gas funding and network metadata can reveal relationships.

## Components

The built-in release deploys seven contracts:

- `PoseidonT3` and `PoseidonT4`: generated hash contracts used by commitments and the tree.
- `ShieldVerifier`: immutable wrapper around the generated Groth16 verifier and verification-key hash.
- `RelayerRegistry`: governance-managed registration of relayer addresses and endpoints.
- `ShieldedPool`: deposits, private spends, swaps, nullifiers, notes and governance.
- `SwapRouter`: routes authorized pool swaps through allowlisted adapters.
- `PancakeV2Adapter`: the PancakeSwap V2 integration for the selected BSC network.

The transaction circuit lives in `protocol/circuits/transaction.circom`.
It uses a two-input/two-output join-split and a depth-20 Poseidon tree.
The public-signal order is `root, publicAmount, extDataHash, token, inputNullifier[2], outputCommitment[2]`.
Use the pool's `hashExtData` and `hashSwap` views; do not independently reconstruct those hashes.

## Browser SDK and account recovery

`web/lib/shield/sdk/` implements note encryption, account keys, encrypted vaults, event discovery, proving, balances and transaction construction.
`web/components/live-shield.tsx` connects those modules to the wallet interface.
Proofs are generated in a browser worker; spend secrets are not sent to the relayer or indexer.

Each Shield account has its own 24-word BIP39 recovery phrase, separate from the connected wallet's phrase.
The local vault uses PBKDF2-SHA256 with 600,000 iterations and AES-GCM encryption.
Users can restore from the phrase or import an encrypted backup and unlock it with its passphrase.
Plaintext seeds, spending keys, blindings and passphrases must not enter persistent React state, browser storage, URLs or logs.
Keep the existing account/network-change locking and vault protections.

Indexer results are checked against onchain roots, spent claims are checked onchain, and discovered notes have their commitments recomputed.
Only registered relayers are used. Their fees are capped and shown before submission.
Keep these checks even when using an indexer or relayer operated by the same team.

## Admin access and governance

The app's `/admin` page is restricted to the connected address:

`0x49b4E7Fe9850FfE6d217c5d658BF5D721Ad50072`

The console checks the selected wallet again before deployment and setup transactions.
This is a frontend restriction. **Contract roles enforce onchain administration independently.**
The governance address entered in the release form becomes the administrator configured in the contracts; the page allowlist does not grant or change those roles.
If governance is a different account or a multisig, export the setup calls and execute them through that governance account.

## Deploy and activate

1. Finalize the trusted setup using `protocol/scripts/ceremony.sh`, then build and test the release as described in `LAUNCH.md`.
2. Open `/admin` with the authorized wallet. Select BSC Testnet for a trial, or BNB Smart Chain for the intended mainnet release.
3. Enter the governance address and choose **Load Shield BSC release**. The console checks each contract's bytecode against the release's recorded hash.
4. Review constructor arguments and gas, then deploy the seven contracts. Each requires a wallet signature and two confirmations before the sequence advances.
5. Run setup with the governance account, or export the setup calls for a multisig. Setup grants roles, connects the router, allowlists the PancakeSwap adapter and enables assets with deposit caps.
6. Export and retain the deployment records. The console rechecks saved deployments before continuing a partially completed release.
7. Run the relayer/indexer from `relayer/` over HTTPS. Register its hot-wallet address and endpoint with the registry using governance. Use the console when governance is the authorized admin wallet; otherwise submit the registry call through governance.
8. Enter the relayer URL and download the app configuration. Publish it as `web/public/shield-deployments.json` with the site.
9. Test small shield, send, swap and withdrawal amounts, then verify recovery in a separate browser session before wider use.

Only publish real, verified deployment addresses. Never commit a local fork's development configuration as a live deployment.
On load, the app checks the chain, pool code, verifier-key hash against configuration, configured swap router and token decimals.
Live actions remain disabled when those checks fail or no deployment is configured.

## Generated artifacts and verification

Do not hand-edit `protocol/src/generated/*`, circuit artifacts or the generated web release/prover assets.
The ceremony and `protocol/scripts/build-manifest.mjs` produce the verifier, hashes, `web/public/shield-release.json` and circuit files.
A circuit or verifier change requires a new pool: finalize a new release and redeploy; do not replace the verifier behind an existing pool.
The prover worker checks artifacts against the release's recorded hashes.

After contract changes, run `forge test`, rebuild with `forge build`, run the release builder, then run the web tests.
Also run the circuit tests for circuit changes, the web typecheck and a production build before release.
Use `/usr/local/bin/node` for direct Node commands on the current development machine.

The phase-2 setup currently has one contribution and a BSC block-hash beacon.
The phase-1 Powers of Tau contribution chain has not been fully verified locally; `zkey verify` against the file did pass.
The operator should add their own phase-2 contribution and finalize before mainnet deployment.
An independent audit and the other open launch checks remain required work; a successful deployment is not evidence of an audit.