Architecture
Four contracts, one SDK and a keeper. What each piece does and how an operation flows through them.
The pieces
| Piece | Role |
|---|---|
| QSHIELD | A standard ERC-20 launched on the Pons V2 launchpad. It trades on its Pons Uniswap v4 pool (ETH pair). It knows nothing about the vault. |
Xmss | A Solidity library: recovers the key and the leaf of a hash-based signature. Pure function, hand-written in assembly. |
QuantumVault | Holds every shielded token. Keeps accounts, keys and leaf counters; verifies signatures; is itself an ERC-4337 account. |
QuantumRouter | Buys with ETH straight into an account, and sells a shielded balance straight to ETH. Holds nothing between transactions. |
FeeHarvester | The token's creator fee recipient on Pons. Splits the fees and turns the holders' half into gas for the vault and tokens donated to it. |
| SDK | TypeScript: key generation, signing, leaf bookkeeping, operation encoding, ERC-4337 submission. |
| Keeper | A small service that calls the permissionless harvest when there is work to do and keeps the vault's price average current. It holds no privileges. |
Entering
wallet ──ETH──▶ QuantumRouter.buy(account, minOut)
│ swap on the Pons market
▼
QuantumVault.shield(account, tokens) ──▶ shares credited to the accountshield can also be called directly by any holder of the token. The account is a bytes32: nothing has to be
registered first.
Operating
An account owner signs an Op with a leaf of the account's key. Two paths carry it to the vault:
┌── any address ──▶ QuantumVault.transact(op, signature)
signed Op ──┤
└── bundler ──▶ EntryPoint ──▶ QuantumVault.validateUserOp (signature checked, books updated)
└─▶ QuantumVault.execute4337 (exit paid out or sold)Both paths end in the same internal function, which enforces the same rules: the signature must recover to the account's current key, and its leaf must not be below the account's counter.
Leaving
An operation with exitShares takes tokens out of the vault's backing. They go to recipient, or to an exitTarget
contract that handles them: the router is one, and turns them into ETH for the recipient.
The loop
every trade ──1% fee──▶ Pons ──creator share──▶ FeeHarvester.harvest()
├─ 50% ─▶ team
└─ 50% ─▶ vault gas deposit (EntryPoint)
└▶ buy QSHIELD ──▶ donated to the vaultThe gas deposit is what lets accounts operate with no ETH. The donated tokens raise the value of every share. Both are funded by trading volume, on-chain, by a function anyone can call.