@pvium/p2id-core 0.1.2 → 0.1.3

package/contracts/PviumIdentity.sol

@@ -5,17 +5,10 @@ import {IVerifier} from "./PviumZKVerifier.sol";
 import {IPviumIdentity} from "./interfaces/IPviumIdentity.sol";
 
 /// @title PviumIdentity
-/// @notice On-chain verifier for Pvium attestations: one deployment per circuit version. The
-///         accepted signer keys start as the Privy app's JWKS at deployment (Privy publishes more
-///         than one key per app and may sign with any of them). The owner manages the set so a
-///         Privy key rotation does not strand deposits: adding a key is proposed with the JWKS URL
-///         and key id it can be checked at, and takes effect after SIGNER_KEY_DELAY (7 days);
-///         removing one is immediate, because a leaked key must stop being trusted at once. A key
-///         proposal is the strongest power here (a forged key forges proofs), which is why it is
-///         public for 7 days: anyone can verify the key at the URL, and payees and funders can
-///         claim or refund before it activates. An owner of address(0) makes the set permanent.
-///         A new circuit build is still a new deployment (plus a new PviumVerifier), which the
-///         P2ID vault factory registers alongside the old one. Developers call it through IPviumIdentity.
+/// @notice Verifies attestations using an immutable proof verifier and circuit version.
+///         The constructor supplies the initial P-256 signer keys. The owner can propose additions
+///         with a 7-day activation delay or remove accepted keys immediately.
+/// @dev Proposal URLs and key ids are metadata; this contract does not validate them against JWKS.
 /// @dev Public input layout emitted by circuit/src/main.nr:
 ///        [0] identity_type   [1] wallet (EVM address checked in-circuit against the token; 0 if none)
 ///        [2] signer_x_hi     [3] signer_x_lo     [4] signer_y_hi   [5] signer_y_lo
@@ -27,19 +20,17 @@ contract PviumIdentity is IPviumIdentity {
     uint256 public constant PUBLIC_INPUT_COUNT = 11;
 
     IVerifier public immutable verifier;
-    /// @notice Circuit version this deployment verifies (see circuit/version.json). One deployment per version.
+    /// @notice Circuit version identifier supplied at deployment; not checked against the verifier's bytecode.
     uint16 public immutable circuitVersion;
     /// @notice Notice a key proposal gives before it can be activated.
     uint64 public constant SIGNER_KEY_DELAY = 7 days;
-    /// @notice Number of accepted signer keys. Zero (every key revoked) refuses every proof until a
-    ///         proposal matures: a freeze, never a payout.
+    /// @notice Number of accepted signer keys. When zero, the signer check rejects attestations.
     uint256 public signerKeyCount;
-    /// @notice Incremented whenever a key is revoked, i.e. whenever proofs that verified before may
-    ///         no longer be trusted. Vaults discard wallets cached under an older revision.
+    /// @notice Incremented by removeSignerKey; exposed to consumers for cache invalidation.
     uint64 public keySetRevision;
     /// @dev Accepted signer keys, keyed by signerKeyHash(x, y).
     mapping(bytes32 keyHash => bool) private _signerKeys;
-    /// @notice Manages the signer key set (two-step transfer); address(0) = the set is permanent.
+    /// @notice Owner authorized to propose/remove keys and transfer ownership; zero disables owner-only calls.
     address public owner;
     address public pendingOwner;
 
@@ -48,7 +39,7 @@ contract PviumIdentity is IPviumIdentity {
         uint256 y;
         /// Earliest activation time; zero when there is no proposal for this key.
         uint64 eta;
-        /// Where the key is published: the JWKS URL and the key id in it, for anyone to check.
+        /// Caller-supplied JWKS URL and key id; stored without publication checks.
         string url;
         string kid;
     }
@@ -62,13 +53,11 @@ contract PviumIdentity is IPviumIdentity {
     event OwnershipTransferStarted(address indexed from, address indexed to);
     event OwnershipTransferred(address indexed from, address indexed to);
 
-    /// @notice Everything an attestation asserts, for Pvium's own contracts (e.g. vault claims
-    ///         that pay `wallet`). Developers should use the IPviumIdentity functions.
+    /// @notice Decoded public inputs returned by verifyAttestation after verification.
     struct Attestation {
         uint8 identityType;
-        /// EVM address of the wallet linked in the same token. The circuit decodes it from the
-        /// signed token and asserts equality, so it is never prover-chosen. Zero when the proof
-        /// carries no wallet or the wallet is not an EVM address (then only walletHash is set).
+        /// EVM wallet public input. The circuit checks the selected wallet against the signed token;
+        /// zero represents an absent or non-EVM wallet.
         address wallet;
         /// When Privy issued the token (unix seconds). Freshness policy is the caller's.
         uint64 iat;
@@ -96,8 +85,9 @@ contract PviumIdentity is IPviumIdentity {
     error TimelockNotElapsed(uint64 eta);
     error UnknownKey(uint256 x, uint256 y);
 
-    /// @param _owner Manages the key set; address(0) fixes the set given here forever.
-    /// @param _signerXs/_signerYs Raw P-256 coordinates of every key the Privy app signs with.
+    /// @param _owner Key-set administrator; address(0) disables owner-only calls.
+    /// @param _signerXs X coordinates of the initial accepted P-256 keys.
+    /// @param _signerYs Corresponding Y coordinates.
     constructor(
         IVerifier _verifier,
         uint16 _circuitVersion,
@@ -124,7 +114,7 @@ contract PviumIdentity is IPviumIdentity {
 
     // ---- signer key management ------------------------------------------------------------
 
-    /// @notice Propose accepting a key, published at `url` under `kid`, after SIGNER_KEY_DELAY.
+    /// @notice Propose a key with caller-supplied `url` and `kid`, eligible after SIGNER_KEY_DELAY.
     ///         Re-proposing a key restarts its delay.
     function proposeSignerKey(uint256 x, uint256 y, string calldata url, string calldata kid) external onlyOwner {
         if (!_isOnCurve(x, y)) revert InvalidPublicKey();
@@ -142,8 +132,7 @@ contract PviumIdentity is IPviumIdentity {
         emit SignerKeyProposalCancelled(x, y);
     }
 
-    /// @notice Accept a proposed key once its delay has passed. Anyone may call it: the owner
-    ///         already decided by proposing, and can still cancel until this runs.
+    /// @notice Accept an uncancelled proposal once its delay has passed. Callable by any address.
     function activateSignerKey(uint256 x, uint256 y) external {
         bytes32 h = signerKeyHash(x, y);
         uint64 eta = signerKeyProposals[h].eta;
@@ -156,10 +145,8 @@ contract PviumIdentity is IPviumIdentity {
         emit SignerKeyAdded(x, y);
     }
 
-    /// @notice Stop accepting a key at once (e.g. Privy retired it, or it leaked). Proofs made from
-    ///         tokens it signed fail from now on, and wallets that vaults cached from any proof are
-    ///         discarded (keySetRevision). Removing the last key is allowed: it freezes claims,
-    ///         which is the safe state while a compromised key is replaced.
+    /// @notice Remove an accepted key and increment keySetRevision. The last key may be removed.
+    ///         Attestations naming this key fail the signer check until it is added again.
     function removeSignerKey(uint256 x, uint256 y) external onlyOwner {
         bytes32 h = signerKeyHash(x, y);
         if (!_signerKeys[h]) revert UnknownKey(x, y);
@@ -210,8 +197,8 @@ contract PviumIdentity is IPviumIdentity {
 
     // ---- lower level ----------------------------------------------------------------------
 
-    /// @notice Verify a proof and return everything it asserts. Reverts unless the proof is valid
-    ///         and was produced from a token signed by one of the accepted keys.
+    /// @notice Check the public-input count and accepted signer, require verifier.verify to return
+    ///         true, and return the decoded attestation.
     function verifyAttestation(bytes calldata proof, bytes32[] calldata publicInputs)
         public
         view
@@ -239,7 +226,7 @@ contract PviumIdentity is IPviumIdentity {
         return a.iat;
     }
 
-    /// @dev Cheap checks first (layout, signer), so bad requests fail before the 4M-gas verify.
+    /// @dev Check input count and signer membership before calling the proof verifier.
     function _decode(bytes32[] calldata publicInputs) internal view returns (Attestation memory a) {
         if (publicInputs.length != PUBLIC_INPUT_COUNT) revert WrongPublicInputCount(publicInputs.length);
         bytes32 x = _join(publicInputs[2], publicInputs[3]);
@@ -256,7 +243,7 @@ contract PviumIdentity is IPviumIdentity {
         return bytes32((uint256(hi) << 128) | uint256(lo));
     }
 
-    /// @dev y^2 == x^3 - 3x + b (mod p) on NIST P-256. Guards against registering a typo.
+    /// @dev Check coordinate bounds and y^2 == x^3 - 3x + b (mod p) on NIST P-256.
     function _isOnCurve(uint256 x, uint256 y) internal pure returns (bool) {
         uint256 p = 0xFFFFFFFF00000001000000000000000000000000FFFFFFFFFFFFFFFFFFFFFFFF;
         uint256 b = 0x5AC635D8AA3A93E7B3EBBD55769886BC651D06B0CC53B0F63BCE3C3E27D2604B;

package/contracts/PviumP2IDPolicy.sol

@@ -4,12 +4,9 @@ pragma solidity ^0.8.27;
 import {IP2IDPolicy} from "./interfaces/IP2IDPolicy.sol";
 
 /// @title PviumP2IDPolicy
-/// @notice The launch policy for P2ID vaults: an owner-managed allowlist of verifiers, and no fee.
-///         Later capabilities (permissionless verifier registration with a stake, protocol fees)
-///         ship as a new policy that the vault factory switches to through its timelock; the
-///         vaults and their addresses do not change.
-/// @dev `owner` should be a Pvium multisig. Approving a verifier only lets payers opt into it;
-///      revoking one freezes claims under it (refunds still work) and never moves funds.
+/// @notice Owner-managed verifier allowlist with a zero fee quote.
+/// @dev Approval checks code presence, not verifier behavior. P2IDVault uses the allowlist for
+///      funding and non-default-verifier claims; its current default verifier bypasses the claim check.
 contract PviumP2IDPolicy is IP2IDPolicy {
     address public owner;
     address public pendingOwner;
@@ -48,7 +45,7 @@ contract PviumP2IDPolicy is IP2IDPolicy {
     }
 
     /// @inheritdoc IP2IDPolicy
-    /// @dev The launch policy charges no fee, so a vault never has fees for it to distribute.
+    /// @dev Distribution is unsupported, including for fees accrued under an earlier policy.
     function distributeFee(address, address, uint256) external payable {
         revert NoFees();
     }

package/contracts/PviumP2IDVaultProxy.sol

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.27;
+
+import {IP2IDVaultProxy} from "./interfaces/IP2IDVaultProxy.sol";
+import {IP2IdVaultFactory} from "./interfaces/IP2IdVaultFactory.sol";
+import {IP2IDVault} from "./interfaces/IP2IDVault.sol";
+import {IP2IDVerifier} from "./interfaces/IP2IDVerifier.sol";
+
+/// @title PviumP2IDVaultProxy
+/// @notice CREATE2 vault proxy initialized from its deploying factory's baseImplementation.
+///         upgradeTo requires a registered target and an identity proof resolving to the caller.
+/// @dev Stores the implementation in the ERC-1967 slot and upgrade history in UPGRADE_SLOT.
+///      Delegated code can write both slots. Proxy-defined selectors take precedence over the
+///      implementation, and empty-calldata native transfers are handled here without delegation.
+contract PviumP2IDVaultProxy is IP2IDVaultProxy {
+    /// @dev bytes32(uint256(keccak256("eip1967.proxy.implementation")) - 1)
+    bytes32 private constant IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;
+    /// @dev bytes32(uint256(keccak256("pvium.vault.proxy.upgrading")) - 1): 1 while upgradeTo runs (a plain slot: the Paris target has no transient storage).
+    bytes32 private constant UPGRADING_SLOT = 0x1355c758876c0a085036d5960a223942d04ee15c92162da025899b2513e77bae;
+    /// @dev bytes32(uint256(keccak256("pvium.vault.proxy.lastUpgrade")) - 1): wallet (160 bits) | iat << 160.
+    bytes32 private constant UPGRADE_SLOT = 0x01d942a94cdff9c1162dd0a9d8cabadc4e9bf5ab8b614fc78cedc4d44e694edf;
+    /// @dev Maximum accepted issue time ahead of block.timestamp, matching P2IDVault.
+    uint64 private constant FUTURE_SLACK = 15 minutes;
+    /// @dev Gas for reading the vault's own freshness floors through the implementation.
+    uint256 private constant READ_GAS = 100_000;
+
+    /// @inheritdoc IP2IDVaultProxy
+    address public immutable factory;
+
+    error NotRegisteredImplementation(address implementation);
+    error NotVaultOf(bytes32 identityHash);
+    error NotOwner(address proven, address caller);
+    error ProofTooOld();
+    error ProofFromFuture();
+    error SameImplementation();
+    error NotAContract(address implementation);
+    error HookNotAcknowledged(address implementation);
+    error UpgradeReentered();
+    error ImplementationChangedDuringHook(address found);
+    error HookDidNotApply(address owner, uint64 latest);
+
+    constructor() {
+        factory = msg.sender;
+        _setImplementation(IP2IdVaultFactory(msg.sender).baseImplementation());
+    }
+
+    /// @inheritdoc IP2IDVaultProxy
+    function implementation() public view returns (address impl) {
+        assembly {
+            impl := sload(IMPLEMENTATION_SLOT)
+        }
+    }
+
+    /// @inheritdoc IP2IDVaultProxy
+    function lastUpgrade() public view returns (address wallet, uint64 iat) {
+        uint256 packed;
+        assembly {
+            packed := sload(UPGRADE_SLOT)
+        }
+        wallet = address(uint160(packed));
+        iat = uint64(packed >> 160);
+    }
+
+    /// @inheritdoc IP2IDVaultProxy
+    function upgradeTo(bytes32 identityHash, address newImplementation, bytes calldata proof) external {
+        _enterUpgrade();
+        IP2IdVaultFactory f = IP2IdVaultFactory(factory);
+        if (f.vaultFor(identityHash) != address(this)) revert NotVaultOf(identityHash);
+        if (!f.isRegisteredImplementation(newImplementation)) revert NotRegisteredImplementation(newImplementation);
+        if (newImplementation == implementation()) revert SameImplementation();
+        address verifier = f.defaultVerifier();
+        (address wallet, uint64 iat) =
+            IP2IDVerifier(verifier).getIdentityWallet(identityHash, proof, IP2IDVerifier.Constraint(bytes32(0), ""));
+        if (wallet != msg.sender) revert NotOwner(wallet, msg.sender);
+        if (iat > block.timestamp + FUTURE_SLACK) revert ProofFromFuture();
+        // Combine stored upgrade history with the readable issue-time floors of the current implementation.
+        (address lastWallet, uint64 lastIat) = lastUpgrade();
+        // Ignore stored history beyond this entry point's accepted future-time bound.
+        if (lastIat > block.timestamp + FUTURE_SLACK) (lastWallet, lastIat) = (address(0), 0);
+        if (iat < lastIat || (iat == lastIat && wallet != lastWallet)) revert ProofTooOld();
+        if (iat < _vaultFloor(verifier)) revert ProofTooOld();
+        uint256 packed = uint256(uint160(wallet)) | (uint256(iat) << 160);
+        assembly {
+            sstore(UPGRADE_SLOT, packed)
+        }
+        _setImplementation(newImplementation);
+        // Apply the verified result through the new implementation. Revert the upgrade on hook
+        // failure, invalid acknowledgement or failed post-condition checks below.
+        (bool ok, bytes memory ret) = address(this).call(abi.encodeCall(IP2IDVault.acceptOwnerProof, (verifier, wallet, iat)));
+        if (!ok) {
+            assembly {
+                revert(add(ret, 32), mload(ret)) // the vault's own reason (ProofTooOld, NotOwnerProof, …)
+            }
+        }
+        // Require a canonical ABI-encoded selector. A fallback returning the same data can satisfy this.
+        if (ret.length != 32 || abi.decode(ret, (bytes4)) != IP2IDVault.acceptOwnerProof.selector) {
+            revert HookNotAcknowledged(newImplementation);
+        }
+        // Post-conditions, read through the new implementation: it is still what was installed,
+        // and it now records this wallet as the payout owner with a floor at least this fresh.
+        // These detect some incompatible hooks. Registered code can fake getters or alter other storage;
+        // the registry does not audit implementation behavior.
+        if (implementation() != newImplementation) revert ImplementationChangedDuringHook(implementation());
+        address ownerNow = address(uint160(_read(abi.encodeCall(IP2IDVault.owner, (verifier)))));
+        uint256 latestNow = _read(abi.encodeCall(IP2IDVault.latestProofIat, (verifier)));
+        if (ownerNow != wallet || latestNow < iat) revert HookDidNotApply(ownerNow, uint64(latestNow));
+        _exitUpgrade();
+    }
+
+    /// @dev upgradeTo is not reentrant: the hook runs with the new implementation installed, and
+    ///      must not be able to start another upgrade from inside this one.
+    function _enterUpgrade() private {
+        uint256 flag;
+        assembly {
+            flag := sload(UPGRADING_SLOT)
+        }
+        if (flag != 0) revert UpgradeReentered();
+        assembly {
+            sstore(UPGRADING_SLOT, 1)
+        }
+    }
+
+    function _exitUpgrade() private {
+        assembly {
+            sstore(UPGRADING_SLOT, 0)
+        }
+    }
+
+    /// @dev Maximum of the current implementation's per-verifier and cross-default floors.
+    ///      Failed, malformed and excessively future-dated reads contribute zero.
+    function _vaultFloor(address verifier) private view returns (uint64 floor) {
+        uint256 a = _read(abi.encodeCall(IP2IDVault.latestProofIat, (verifier)));
+        uint256 b = _read(abi.encodeCall(IP2IDVault.untrackedProofIat, ()));
+        // Discard values beyond the same future-time bound used for proofs.
+        uint256 limit = block.timestamp + FUTURE_SLACK;
+        if (a > limit) a = 0;
+        if (b > limit) b = 0;
+        floor = uint64(a > b ? a : b);
+    }
+
+    function _read(bytes memory data) private view returns (uint256 value) {
+        (bool ok, bytes memory ret) = address(this).staticcall{gas: READ_GAS}(data);
+        if (!ok || ret.length != 32) return 0;
+        value = abi.decode(ret, (uint256));
+    }
+
+    /// @dev Accepted here, not delegated: keeps plain sends within the 2300-gas stipend.
+    receive() external payable {}
+
+    fallback() external payable {
+        address impl = implementation();
+        assembly {
+            calldatacopy(0, 0, calldatasize())
+            let ok := delegatecall(gas(), impl, 0, calldatasize(), 0, 0)
+            returndatacopy(0, 0, returndatasize())
+            switch ok
+            case 0 { revert(0, returndatasize()) }
+            default { return(0, returndatasize()) }
+        }
+    }
+
+    function _setImplementation(address impl) private {
+        if (impl.code.length == 0) revert NotAContract(impl);
+        assembly {
+            sstore(IMPLEMENTATION_SLOT, impl)
+        }
+        emit Upgraded(impl);
+    }
+}

package/contracts/PviumP2IdVaultFactory.sol

@@ -4,33 +4,40 @@ pragma solidity ^0.8.27;
 import {IP2IdVaultFactory} from "./interfaces/IP2IdVaultFactory.sol";
 import {IP2IDPolicy} from "./interfaces/IP2IDPolicy.sol";
 import {P2IDVault} from "./P2IDVault.sol";
+import {PviumP2IDVaultProxy} from "./PviumP2IDVaultProxy.sol";
+import {IP2IDVault} from "./interfaces/IP2IDVault.sol";
 
 /// @title PviumP2IdVaultFactory
-/// @notice Deploys P2IDVaults with CREATE2, salted by identity hash, and points them at the
-///         current policy (which verifiers are allowed, what capped fee applies) and default verifier. A vault takes no constructor arguments
-///         (the factory calls `initialize` right after `new`), so its creation code is a constant
-///         and an identity's vault address is
-///         `keccak256(0xff ‖ factory ‖ identityHash ‖ keccak256(creationCode))`, computable
-///         anywhere from two constants. Funds sent to that address before deployment are swept
-///         by the owner after deployment (see P2IDVault: bare transfers are untracked and irrevocable).
-/// @dev Everything expected to evolve is in the policy (IP2IDPolicy), so this factory and the vault
-///      code, which fix every P2ID address, never have to change. Both move only through a
-///      timelock (propose, wait, activate): the policy after `policyChangeDelay`, the default
-///      verifier after DEFAULT_VERIFIER_DELAY, a fixed 14 days. Direct transfers follow the default
-///      verifier and have no refund path, so a change to it gets the longer notice: anyone who
-///      objects can sweep first, and the vault guarantees nothing can freeze their claim meanwhile.
-///      What a policy can do is bounded by the vault (fee cap, fees fixed at funding, no fee on
-///      refunds, never redirecting a payout, never blocking claims through the default verifier).
+/// @notice Deploys one PviumP2IDVaultProxy per identity with CREATE2 (salt = identityHash) and
+///         supplies policy and default-verifier settings. The proxy takes no constructor arguments;
+///         its address is the low 160 bits of keccak256(0xff || factory || identityHash || initCodeHash()).
+/// @dev The policy and the default verifier change only through a timelock (propose, wait,
+///      activate): the policy after `policyChangeDelay`, the default verifier after the fixed
+///      DEFAULT_VERIFIER_DELAY. Implementation registration also has a timelock; revocation is
+///      immediate and does not change existing proxies. Vault upgrades preserve their addresses.
+///      Manual registration checks code presence; deterministic deployment also checks factory binding.
+///      Neither path verifies storage compatibility or implementation behavior.
 contract PviumP2IdVaultFactory is IP2IdVaultFactory {
     bytes32 public immutable nsHash;
+    /// @notice Starting implementation for new proxies, changed only by a delayed default proposal.
+    address public baseImplementation;
+    /// @notice Original implementation, kept registered as a fallback.
+    address public immutable initialImplementation;
+    bytes32 public constant IMPLEMENTATION_SALT = keccak256("pvium.vault.implementation.v1");
+    bool public proposedImplementationMakeDefault;
+    /// @notice Target allowlist checked by PviumP2IDVaultProxy.upgradeTo.
+    mapping(address implementation => bool) public isRegisteredImplementation;
+    address public proposedImplementation;
+    /// @notice Earliest time the proposed implementation can be registered; 0 when nothing is proposed.
+    uint64 public proposedImplementationEta;
     uint64 public immutable minRefundWindow;
     uint64 public immutable maxRefundWindow;
 
-    /// @notice Proposes and activates policy / default-verifier changes (a Pvium multisig). Two-step transfer.
+    /// @notice Administrative owner for settings and implementation registration; transferred in two steps.
     address public owner;
     address public pendingOwner;
 
-    /// @notice The policy every vault consults. Changes only via the timelock below.
+    /// @notice Policy address returned to vaults; changed through proposePolicy/activatePolicy.
     address public policy;
     /// @notice Verifier used when a payer does not choose one. Changes only via the timelock below.
     address public defaultVerifier;
@@ -67,6 +74,8 @@ contract PviumP2IdVaultFactory is IP2IdVaultFactory {
     error TokenBalanceQueryFailed();
     error NothingReceived();
     error UnexpectedValue();
+    error InvalidImplementation();
+    error ImplementationProposalPending();
 
     constructor(
         address _owner,
@@ -91,6 +100,113 @@ contract PviumP2IdVaultFactory is IP2IdVaultFactory {
         emit PolicyActivated(_policy);
         defaultVerifier = _defaultVerifier;
         emit DefaultVerifierActivated(_defaultVerifier);
+        address base = address(new P2IDVault(address(this)));
+        baseImplementation = base;
+        initialImplementation = base;
+        isRegisteredImplementation[base] = true;
+        emit ImplementationRegistered(base);
+    }
+
+    // ------------------------------------------------------------------ vault implementations (timelocked)
+
+    /// @notice Predict the CREATE2 address from full creation code, including constructor arguments.
+    function implementationFor(bytes32 creationCodeHash) public view returns (address) {
+        return address(uint160(uint256(keccak256(abi.encodePacked(
+            bytes1(0xff), address(this), IMPLEMENTATION_SALT, creationCodeHash
+        )))));
+    }
+
+    /// @notice Deploy full creation code with CREATE2 and propose registration in the same transaction.
+    /// @dev Reuses existing code. An identical pending proposal keeps its ETA; a different proposal
+    ///      must first be cancelled. makeDefault affects new proxies only, after registration.
+    function deployVaultImplementation(bytes memory creationCode, bool makeDefault)
+        external onlyOwner returns (address implementation)
+    {
+        if (creationCode.length == 0) revert InvalidImplementation();
+        implementation = implementationFor(keccak256(creationCode));
+        if (implementation.code.length == 0) {
+            bytes32 salt = IMPLEMENTATION_SALT;
+            address deployed;
+            assembly {
+                deployed := create2(0, add(creationCode, 32), mload(creationCode), salt)
+            }
+            if (deployed != implementation || deployed.code.length == 0) revert InvalidImplementation();
+            emit ImplementationDeployed(implementation, keccak256(creationCode));
+        }
+        _checkFactoryBinding(implementation);
+        if (proposedImplementationEta != 0) {
+            if (proposedImplementation != implementation || proposedImplementationMakeDefault != makeDefault) {
+                revert ImplementationProposalPending();
+            }
+            return implementation;
+        }
+        if (isRegisteredImplementation[implementation] && (!makeDefault || baseImplementation == implementation)) {
+            return implementation;
+        }
+        _proposeImplementation(implementation, makeDefault);
+    }
+
+    /// @notice Propose an opt-in upgrade target. Replaces a pending proposal and resets its delay.
+    function proposeImplementation(address implementation) external onlyOwner {
+        if (implementation.code.length == 0 || isRegisteredImplementation[implementation]) revert InvalidImplementation();
+        _proposeImplementation(implementation, false);
+    }
+
+    /// @notice Propose a registered target as the starting implementation for future proxies.
+    function proposeDefaultImplementation(address implementation) external onlyOwner {
+        if (!isRegisteredImplementation[implementation] || implementation == baseImplementation) revert InvalidImplementation();
+        _checkFactoryBinding(implementation);
+        _proposeImplementation(implementation, true);
+    }
+
+    function _proposeImplementation(address implementation, bool makeDefault) private {
+        proposedImplementation = implementation;
+        proposedImplementationMakeDefault = makeDefault;
+        proposedImplementationEta = uint64(block.timestamp) + DEFAULT_VERIFIER_DELAY;
+        emit ImplementationProposed(implementation, proposedImplementationEta);
+        emit ImplementationDefaultProposed(implementation, makeDefault, proposedImplementationEta);
+    }
+
+    function _checkFactoryBinding(address implementation) private view {
+        (bool ok, bytes memory result) = implementation.staticcall(abi.encodeWithSignature("factory()"));
+        if (!ok || result.length != 32 || abi.decode(result, (bytes32)) != bytes32(uint256(uint160(address(this))))) {
+            revert InvalidImplementation();
+        }
+    }
+
+    function cancelImplementationProposal() external onlyOwner {
+        if (proposedImplementationEta == 0) revert NothingProposed();
+        emit ImplementationProposalCancelled(proposedImplementation);
+        delete proposedImplementation;
+        delete proposedImplementationEta;
+        delete proposedImplementationMakeDefault;
+    }
+
+    function registerImplementation() external onlyOwner {
+        uint64 eta = proposedImplementationEta;
+        if (eta == 0) revert NothingProposed();
+        if (block.timestamp < eta) revert TimelockNotElapsed(eta);
+        address implementation = proposedImplementation;
+        bool makeDefault = proposedImplementationMakeDefault;
+        if (implementation.code.length == 0) revert InvalidImplementation();
+        if (makeDefault) _checkFactoryBinding(implementation);
+        delete proposedImplementation;
+        delete proposedImplementationEta;
+        delete proposedImplementationMakeDefault;
+        isRegisteredImplementation[implementation] = true;
+        emit ImplementationRegistered(implementation);
+        if (makeDefault) {
+            baseImplementation = implementation;
+            emit DefaultImplementationActivated(implementation);
+        }
+    }
+
+    /// @notice Remove a registered target immediately, except the current default and original implementation.
+    ///         This changes the registry, not the implementation stored in existing proxies.
+    function revokeImplementation(address implementation) external onlyOwner {
+        if (implementation == baseImplementation || implementation == initialImplementation || !isRegisteredImplementation[implementation]) revert InvalidImplementation();
+        isRegisteredImplementation[implementation] = false;
+        emit ImplementationRevoked(implementation);
     }
 
     // ------------------------------------------------------------------ policy (timelocked)
@@ -111,8 +227,7 @@ contract PviumP2IdVaultFactory is IP2IdVaultFactory {
         delete proposedPolicyEta;
     }
 
-    /// @notice Switch every vault to the proposed policy once the delay has elapsed. The new policy
-    ///         must allow the current default verifier, so bare transfers stay claimable.
+    /// @notice Set policy after the proposal delay, provided it approves the current default verifier.
     function activatePolicy() external onlyOwner {
         uint64 eta = proposedPolicyEta;
         if (eta == 0) revert NothingProposed();
@@ -144,8 +259,8 @@ contract PviumP2IdVaultFactory is IP2IdVaultFactory {
         delete proposedDefaultEta;
     }
 
-    /// @notice Make the proposed verifier the default once the delay has elapsed. The policy must
-    ///         still allow it (a revocation in the meantime cancels it in effect).
+    /// @notice Set the proposed default after its delay, provided the current policy approves it.
+    ///         Failed approval leaves the proposal pending.
     function activateDefaultVerifier() external onlyOwner {
         uint64 eta = proposedDefaultEta;
         if (eta == 0) revert NothingProposed();
@@ -201,18 +316,17 @@ contract PviumP2IdVaultFactory is IP2IdVaultFactory {
         return vaultFor(identityHash).code.length != 0;
     }
 
-    /// @notice keccak256 of the P2IDVault creation code (no constructor arguments), for offline derivation.
+    /// @notice keccak256 of the vault proxy's creation code (no constructor arguments), for offline derivation.
     function initCodeHash() public pure returns (bytes32) {
-        return keccak256(type(P2IDVault).creationCode);
+        return keccak256(type(PviumP2IDVaultProxy).creationCode);
     }
 
     /// @inheritdoc IP2IdVaultFactory
     function deploy(bytes32 identityHash) public returns (address vault) {
         vault = vaultFor(identityHash);
         if (vault.code.length != 0) return vault;
-        P2IDVault v = new P2IDVault{salt: identityHash}();
-        v.initialize(nsHash, identityHash, minRefundWindow, maxRefundWindow);
-        vault = address(v);
+        vault = address(new PviumP2IDVaultProxy{salt: identityHash}());
+        IP2IDVault(vault).initialize(nsHash, identityHash, minRefundWindow, maxRefundWindow);
         emit VaultDeployed(identityHash, vault);
     }
 
@@ -274,8 +388,8 @@ contract PviumP2IdVaultFactory is IP2IdVaultFactory {
             return (vault, P2IDVault(payable(vault)).fundFor{value: msg.value}(msg.sender, verifier, token, amount, constraint, refundWindow, ref));
         }
         if (msg.value != 0) revert UnexpectedValue();
-        // Collect from the payer (credit what actually arrived, for fee-on-transfer tokens),
-        // then let the vault pull exactly that and record the payer as funder.
+        // Measure the factory's balance increase, approve that amount to the vault, and record
+        // msg.sender as funder. The vault measures its own balance increase during the second transfer.
         uint256 before = _balanceOf(token);
         _callToken(
             token,