Contracts
The external interface of the vault, the router and the harvester.
Solidity 0.8.26, built with Foundry. Sources are in contracts/src.
QuantumVault
Entering
function shield(bytes32 account, uint256 amount) external returns (uint256 shares);
function donate(uint256 amount) external;
function absorb() external returns (uint256 amount);shield requires an approval for amount. account must be a key somebody holds: tokens shielded to an arbitrary
value have no signer.
Operating
function transact(Op calldata op, bytes calldata signature) external;
// ERC-4337 (EntryPoint only)
function validateUserOp(PackedUserOperation calldata userOp, bytes32, uint256 missingAccountFunds) external returns (uint256);
function execute4337(uint256 id) external;
function claimExit(uint256 id) external;Reading
function accounts(bytes32 account) external view returns (bytes32 key, uint64 nextLeaf, uint64 epoch);
function keyOf(bytes32 account) external view returns (bytes32);
function sharesOf(bytes32 account) external view returns (uint256);
function assetsOf(bytes32 account) external view returns (uint256);
function convertToShares(uint256 assets) external view returns (uint256);
function convertToAssets(uint256 shares) external view returns (uint256);
function opDigest(Op memory op) external view returns (bytes32);
function opId(bytes32 account, uint64 epoch, uint256 leaf) external pure returns (uint256);
function totalBacking() external view returns (uint256);
function totalShares() external view returns (uint256);
function pendingExitTotal() external view returns (uint256);
function tokensPerEthEma() external view returns (uint256);
function networkFee() external view returns (uint128);
function previousNetworkFee() external view returns (uint128);
function maxOpCostWei() external view returns (uint256);
function entriesPaused() external view returns (bool);Price
function poke() external;Events
| Event | Emitted when |
|---|---|
Shielded(account, from, amount, shares) | Tokens enter an account |
Operated(account, opId, epoch, leaf) | A signed operation is applied |
Transferred(from, to, shares) | Shares move between accounts |
Exited(account, opId, recipient, amount, shares) | Tokens leave the backing |
ExitSettled(opId, byTarget) | An exit has been paid out |
KeyChanged(account, newKey, epoch) | An account replaces its key |
Donation(from, amount) | Tokens are added for every account |
VaultUpdated(totalBacking, totalShares) | The exchange rate changes |
PriceUpdated(tokensPerEthEma) | The price average moves |
NetworkFeeUpdated(networkFee) | The network fee is recomputed |
An account's full history is the set of logs indexed by its name: no indexer is needed beyond eth_getLogs.
Errors
InvalidSignature, LeafAlreadyUsed, KeyUnchanged, InsufficientShares, Expired, WrongCaller,
InsufficientGasFee, GasCostAboveLimit, InvalidUserOp, NotEntryPoint, NoPrice, NoSuchExit,
EntriesArePaused, NotGuardian, ZeroAddress, ZeroAccount, ZeroShares.
QuantumRouter
function buy(bytes32 account, uint256 minTokensOut) external payable returns (uint256 tokensOut);
function quote(bool isBuy, uint256 amountIn) external returns (uint256 amountOut);
function onShieldExit(uint256 amount, address ethRecipient, bytes calldata data) external; // vault onlyEvents: Bought(account, ethIn, tokensOut), Sold(ethRecipient, tokensIn, ethOut).
FeeHarvester
function harvest() external returns (uint256 tokensDonated);
function payTeam() external;
function claimable() external view returns (uint256);
function setTeamRecipient(address newRecipient) external; // owner
function proposeSuccessor(address successor) external; // owner
function cancelSuccessor() external; // owner
function executeSuccessor() external; // anyone, after SUCCESSOR_DELAY
function transferOwnership(address newOwner) external; // ownerEvents: Harvested(ethAvailable, ethToDeposit, ethSpent, tokensDonated), TeamShareAccrued, TeamPaid,
CallerTipped, SuccessorProposed, SuccessorCancelled, FeeRecipientHandedOver.
Xmss
library Xmss {
function recover(bytes32 digest, bytes memory sig) internal pure returns (bytes32 key, uint256 leaf);
}A self-contained library with no dependencies. See the signature scheme.
Tests
The Foundry suite covers the signature library against vectors from the TypeScript implementation, the vault's accounting, the ERC-4337 path against the real EntryPoint, stateful invariants on the vault's books, and the Pons integration on a fork of Robinhood Chain.
pnpm contracts:test