Security model
What protects a shielded balance, what each role can do, and what the design guarantees.
What a shielded balance rests on
| Assumption | Used for |
|---|---|
| keccak256 is preimage and second-preimage resistant | Every signature. This is the only cryptographic assumption between a secret and its funds. |
| The EVM executes the vault's code | Same as every contract on the chain |
No elliptic curve, no pairing, no trusted setup, no off-chain verifier and no oracle appear in the path that authorizes a movement. Hash-based signatures are the most conservative post-quantum family: their security reduces to the hash function itself, and it is the family standardized for long-lived keys (XMSS in RFC 8391 and NIST SP 800-208, SLH-DSA in FIPS 205).
Against a quantum adversary, keccak256 retains 128 bits of preimage security. Tweakable hashing binds every hash to its key and position, so attacking many accounts at once is no cheaper than attacking one.
Guarantees enforced by the vault
- Only the key moves the balance. Every path that reduces an account's shares goes through
Xmss.recoverand a comparison with the account's current key. - A leaf is accepted once. The per-account counter only moves forward; a key change resets it under a new epoch that invalidates everything signed before.
- Signatures are bound to their context. Chain ID, vault address, epoch and the full operation are in the digest. Nothing can be replayed elsewhere or later.
- Couriers cannot alter an operation. Amounts, recipient, exit target, exit parameters, minimum execution gas and deadline are all signed. A bundler or submitting wallet chooses only the gas price, capped by an immutable.
- The books cover the tokens.
token.balanceOf(vault) ≥ totalBacking + pendingExitTotalholds across every operation; it is checked by stateful invariant tests. - Exits cannot be trapped. A failing exit target sends the tokens to the recipient; an exit whose execution ran
out of gas is released by
claimExit, callable by anyone.
No administrator
| Capability | Exists? |
|---|---|
| Upgrade the vault or the router | No |
| Change the token, the market, the EntryPoint or the fee limit | No: immutable |
| Move, freeze or seize an account's balance | No |
| Pause transfers, sales, exits or key changes | No |
Pause new entries (shield) | Guardian only |
| Change where the team's half of the fees goes | Harvester owner |
| Redirect the token's creator fees | Harvester owner, publicly, after a 24-hour delay |
| Touch the holders' half of the fees | No |
The guardian's switch exists so that new deposits can be stopped; it has no effect on anything already inside.
The market-facing parts
- Price average. The network fee and the harvester's price limit use an average that folds in one clamped observation per block. A price held for one block cannot move it more than a single bounded step.
- Harvester buys. At most one per L1 block, at most 0.5% of price impact, never more than 15% above the average. Sandwiching them costs more in fees than it can extract.
- Gas deposit. An operation's maximum cost is capped at
maxOpCostWei, and the fee it pays is worth that cap, so the deposit cannot be drained through accounts. - Reentrancy.
shield,donate,absorb,transactand exit settlement share a transient lock, and exited tokens stay accounted for until they have left the vault.
The owner's side
Hash-based keys ask two things of whoever holds them, and the app does both:
- Never sign two different messages with one leaf. The wallet records each leaf before its signature leaves the signer, reuses the same signature for the same operation, and skips ahead after a restore.
- Keep the secret. It is generated in the browser, encrypted at rest (AES-256-GCM under PBKDF2-SHA-256, 600,000 rounds) and never transmitted. The 24 words are its only copy outside the device.
Scope
Quantum Shield protects the authorization of shielded balances. Tokens outside the vault are ordinary ERC-20 balances under their wallet's key, and the chain itself orders and executes transactions as it does for every contract. Shielded accounts and balances are public.