@pvium/p2id-core 0.1.2 → 0.2.0

package/contracts/PviumP2IdVaultFactory.sol

@@ -4,33 +4,151 @@ 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 {IP2IDVerifier} from "./interfaces/IP2IDVerifier.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 {
+    /// @notice Alpha proof-acceptance status by pinned verification-key SHA-256.
+    /// @dev Inverted storage: a key is in alpha unless it has been released, so a verification key
+    ///      nobody has configured (a new circuit) requires attestation from its first proof.
+    mapping(bytes32 => bool) public alphaReleased;
+    mapping(bytes32 => uint256) public alphaRevision;
+    address public defaultAttester;
+    uint256 public alphaEpoch;
+    bytes32 public constant ALPHA_AUTHORIZATION_TYPEHASH =
+        keccak256(
+            "AlphaAuthorization(address vault,address caller,bytes32 callHash,uint256 nonce,uint256 deadline,uint256 epoch)"
+        );
+    event AlphaModeSet(bytes32 indexed vkHash, bool enabled, uint256 epoch);
+    event DefaultAttesterSet(address attester, uint256 epoch);
+    error InvalidAlphaAuthorization();
+    error AlphaAuthorizationExpired();
+    error InvalidVkHash();
+
+    /// @notice Whether proofs under `vkHash` need an alpha attestation. True for every key until
+    ///         the owner releases it with setAlpha(vkHash, false).
+    function isAlpha(bytes32 vkHash) public view returns (bool) {
+        return !alphaReleased[vkHash];
+    }
+
+    function setAlpha(bytes32 vkHash, bool enabled) external onlyOwner {
+        if (vkHash == bytes32(0)) revert InvalidVkHash();
+        if (enabled && alphaReleased[vkHash]) ++alphaRevision[vkHash]; // back into alpha: voids owners cached while released
+        alphaReleased[vkHash] = !enabled;
+        ++alphaEpoch;
+        emit AlphaModeSet(vkHash, enabled, alphaEpoch);
+    }
+
+    /// @notice Replace the alpha attester immediately; invalidates outstanding alpha approvals.
+    function setDefaultAttester(address attester) external onlyOwner {
+        if (attester == address(0)) revert InvalidAlphaAuthorization();
+        defaultAttester = attester;
+        ++alphaEpoch;
+        emit DefaultAttesterSet(attester, alphaEpoch);
+    }
+
+    function alphaAuthorizationDigest(
+        address vault,
+        address caller,
+        bytes32 callHash,
+        uint256 nonce,
+        uint256 deadline
+    ) public view returns (bytes32) {
+        bytes32 domain = keccak256(
+            abi.encode(
+                keccak256(
+                    "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"
+                ),
+                keccak256("PviumAlpha"),
+                keccak256("1"),
+                block.chainid,
+                address(this)
+            )
+        );
+        return
+            keccak256(
+                abi.encodePacked(
+                    "\x19\x01",
+                    domain,
+                    keccak256(
+                        abi.encode(
+                            ALPHA_AUTHORIZATION_TYPEHASH,
+                            vault,
+                            caller,
+                            callHash,
+                            nonce,
+                            deadline,
+                            alphaEpoch
+                        )
+                    )
+                )
+            );
+    }
+
+    function verifyAlphaAuthorization(
+        address vault,
+        address caller,
+        bytes32 callHash,
+        uint256 nonce,
+        uint256 deadline,
+        bytes calldata signature
+    ) external view {
+        if (block.timestamp > deadline) revert AlphaAuthorizationExpired();
+        if (signature.length != 65) revert InvalidAlphaAuthorization();
+        bytes32 r;
+        bytes32 s;
+        uint8 v;
+        assembly {
+            r := calldataload(signature.offset)
+            s := calldataload(add(signature.offset, 32))
+            v := byte(0, calldataload(add(signature.offset, 64)))
+        }
+        if (
+            (v != 27 && v != 28) ||
+            uint256(s) >
+            0x7fffffffffffffffffffffffffffffff5d576e7357a4501ddfe92f46681b20a0
+        ) revert InvalidAlphaAuthorization();
+        address signer = ecrecover(
+            alphaAuthorizationDigest(vault, caller, callHash, nonce, deadline),
+            v,
+            r,
+            s
+        );
+        if (signer == address(0) || signer != defaultAttester)
+            revert InvalidAlphaAuthorization();
+    }
     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 +185,8 @@ contract PviumP2IdVaultFactory is IP2IdVaultFactory {
     error TokenBalanceQueryFailed();
     error NothingReceived();
     error UnexpectedValue();
+    error InvalidImplementation();
+    error ImplementationProposalPending();
 
     constructor(
         address _owner,
@@ -75,13 +195,19 @@ contract PviumP2IdVaultFactory is IP2IdVaultFactory {
         address _defaultVerifier,
         uint64 _policyChangeDelay,
         uint64 _minRefundWindow,
-        uint64 _maxRefundWindow
+        uint64 _maxRefundWindow,
+        address _alphaAttester
     ) {
         if (_owner == address(0)) revert InvalidOwner();
         if (_minRefundWindow > _maxRefundWindow) revert InvalidRefundWindow();
         if (_policy.code.length == 0) revert InvalidPolicy();
-        if (!IP2IDPolicy(_policy).isVerifierAllowed(_defaultVerifier)) revert VerifierNotApproved(_defaultVerifier);
+        if (!IP2IDPolicy(_policy).isVerifierAllowed(_defaultVerifier))
+            revert VerifierNotApproved(_defaultVerifier);
         owner = _owner;
+        defaultAttester = _alphaAttester == address(0)
+            ? _owner
+            : _alphaAttester;
+        emit DefaultAttesterSet(defaultAttester, alphaEpoch);
         emit OwnershipTransferred(address(0), _owner);
         nsHash = _nsHash;
         policyChangeDelay = _policyChangeDelay;
@@ -91,6 +217,175 @@ 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;
+        bytes32 initialVkHash = IP2IDVerifier(_defaultVerifier).vkHash();
+        if (initialVkHash == bytes32(0)) revert InvalidVkHash();
+        alphaRevision[initialVkHash] = 1; // in alpha by default, like every key
+        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();
+        _checkFactoryBinding(implementation); // bound to this factory, however it was deployed
+        _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();
+        _checkFactoryBinding(implementation); // re-checked at registration: the code could not change, but the rule is one
+        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,14 +406,14 @@ 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();
         if (block.timestamp < eta) revert TimelockNotElapsed(eta);
         address newPolicy = proposedPolicy;
-        if (!IP2IDPolicy(newPolicy).isVerifierAllowed(defaultVerifier)) revert VerifierNotApproved(defaultVerifier);
+        if (!IP2IDPolicy(newPolicy).isVerifierAllowed(defaultVerifier))
+            revert VerifierNotApproved(defaultVerifier);
         delete proposedPolicy;
         delete proposedPolicyEta;
         policy = newPolicy;
@@ -131,7 +426,8 @@ contract PviumP2IdVaultFactory is IP2IdVaultFactory {
     ///         after DEFAULT_VERIFIER_DELAY (14 days), via activateDefaultVerifier(). Replaces any
     ///         pending proposal.
     function proposeDefaultVerifier(address verifier) external onlyOwner {
-        if (!IP2IDPolicy(policy).isVerifierAllowed(verifier)) revert VerifierNotApproved(verifier);
+        if (!IP2IDPolicy(policy).isVerifierAllowed(verifier))
+            revert VerifierNotApproved(verifier);
         proposedDefaultVerifier = verifier;
         proposedDefaultEta = uint64(block.timestamp) + DEFAULT_VERIFIER_DELAY;
         emit DefaultVerifierProposed(verifier, proposedDefaultEta);
@@ -144,14 +440,15 @@ 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();
         if (block.timestamp < eta) revert TimelockNotElapsed(eta);
         address verifier = proposedDefaultVerifier;
-        if (!IP2IDPolicy(policy).isVerifierAllowed(verifier)) revert VerifierNotApproved(verifier);
+        if (!IP2IDPolicy(policy).isVerifierAllowed(verifier))
+            revert VerifierNotApproved(verifier);
         delete proposedDefaultVerifier;
         delete proposedDefaultEta;
         defaultVerifier = verifier;
@@ -201,18 +498,22 @@ 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);
     }
 
@@ -271,11 +572,22 @@ contract PviumP2IdVaultFactory is IP2IdVaultFactory {
         vault = deploy(identityHash);
         if (token == address(0)) {
             // Native coin: forward exactly the value sent; the vault checks it equals `amount`.
-            return (vault, P2IDVault(payable(vault)).fundFor{value: msg.value}(msg.sender, verifier, token, amount, constraint, refundWindow, ref));
+            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,

package/contracts/PviumVerifier.sol

@@ -6,22 +6,16 @@ import {P2IDHash} from "./lib/P2IDHash.sol";
 import {PviumIdentity} from "./PviumIdentity.sol";
 
 /// @title PviumVerifier
-/// @notice IP2IDVerifier backed by the Pvium ZK circuit. Verifies an identity proof against the
-///         registered Privy signing key (via PviumIdentity) and, when a constraint commitment is
-///         given, that the registered attestation signer has signed that commitment.
+/// @notice Resolves an EVM wallet from a PviumIdentity attestation and checks an optional
+///         constraint signature against the registered constraint signers.
 /// @dev proof = abi.encode(bytes zkProof, bytes32[] publicInputs). The wallet returned is the
 ///      EVM address the circuit read out of the Privy-signed token (public input 1), cross-checked
 ///      here against the proof's walletHash with the same formula. A constraint is satisfied by
 ///      a registered signer's EIP-712 signature over `Constraint(bytes32 commitment)` in this
-///      contract's domain (name "PviumVerifier", version "1", chain id, this address), so a
-///      signature is valid on one chain and one verifier only. The identity side is immutable
-///      (a new key set or circuit is a new deployment the vault factory registers alongside).
-///      The signer set is the owner's: signers only gate constrained deposits, and never choose
-///      the wallet, so a compromised signer or owner can release screened funds to their rightful
-///      payee early but cannot redirect them. An owner of address(0) freezes the set.
-///      What a commitment means is up to the funder; for a screening attestation it should
-///      commit to the payee as well as the policy, plus a salt (see screeningCommitment),
-///      otherwise one signature releases every deposit under that policy for every payee.
+///      contract's domain (name "PviumVerifier", version "1", chain id, this address).
+///      The PviumIdentity address is immutable; its accepted key set can change separately.
+///      Constraint signatures authorize a commitment, while the attestation supplies the wallet.
+///      This contract does not interpret the commitment's contents or enforce signature single-use.
 contract PviumVerifier is IP2IDVerifier {
     bytes32 private constant EIP712_DOMAIN_TYPEHASH =
         keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)");
@@ -51,7 +45,7 @@ contract PviumVerifier is IP2IDVerifier {
     error NotPendingOwner();
     error InvalidSigner();
 
-    /// @param _owner  Manages the signer set; address(0) makes the set given here permanent.
+    /// @param _owner Constraint-signer administrator; address(0) disables owner-only calls.
     /// @param _signers Initial constraint signers (may be empty: constraints unsupported until one is added).
     constructor(PviumIdentity _pviumIdentity, address _owner, address[] memory _signers) {
         pviumIdentity = _pviumIdentity;
@@ -62,8 +56,7 @@ contract PviumVerifier is IP2IDVerifier {
         _cachedDomainSeparator = _domainSeparator(block.chainid);
     }
 
-    /// @notice Register or revoke a constraint signer. Revoking one makes its signatures fail from
-    ///         now on, including for deposits already funded; those wait for a registered signer.
+    /// @notice Set a constraint signer's membership. Signatures are checked against current membership.
     function setConstraintSigner(address signer, bool allowed) external onlyOwner {
         _setSigner(signer, allowed);
     }
@@ -80,7 +73,7 @@ contract PviumVerifier is IP2IDVerifier {
         pendingOwner = address(0);
     }
 
-    /// @notice EIP-712 domain separator; recomputed if the chain id changes (chain fork).
+    /// @notice EIP-712 domain separator; recomputed when block.chainid differs from its deployment value.
     function DOMAIN_SEPARATOR() public view returns (bytes32) {
         return block.chainid == _cachedChainId ? _cachedDomainSeparator : _domainSeparator(block.chainid);
     }
@@ -97,7 +90,7 @@ contract PviumVerifier is IP2IDVerifier {
     ) external view returns (address wallet, uint64 iat) {
         (bytes memory zkProof, bytes32[] memory publicInputs) = abi.decode(proof, (bytes, bytes32[]));
 
-        // Reverts (InvalidProof / UnknownSigner / …) unless the proof is valid under the registered key.
+        // Verify against PviumIdentity's current accepted signer set.
         PviumIdentity.Attestation memory a = pviumIdentity.verifyAttestation(zkProof, publicInputs);
         if (a.identityHash != identityHash) revert IdentityMismatch();
         if (a.wallet == address(0)) revert NoEvmWallet();
@@ -110,9 +103,10 @@ contract PviumVerifier is IP2IDVerifier {
         return (a.wallet, a.iat);
     }
 
+    function vkHash() external view returns (bytes32) { return pviumIdentity.vkHash(); }
+
     /// @inheritdoc IP2IDVerifier
-    /// @dev Attester changes never affect which wallet a proof resolves to, so only the identity
-    ///      contract's key revocations count.
+    /// @dev Forward the identity key-set revision; constraint-signer changes do not increment it.
     function revision() external view returns (uint64) {
         return pviumIdentity.keySetRevision();
     }
@@ -127,8 +121,8 @@ contract PviumVerifier is IP2IDVerifier {
         return keccak256(abi.encodePacked("\x19\x01", DOMAIN_SEPARATOR(), keccak256(abi.encode(CONSTRAINT_TYPEHASH, commitment))));
     }
 
-    /// @notice Suggested commitment for a screening attestation: binds the policy to the payee, with
-    ///         a random salt so each deposit has its own commitment (a funder can use one only once).
+    /// @notice Hash policyHash, identityHash and caller-supplied salt using abi.encode.
+    ///         Does not generate a salt or enforce uniqueness.
     function screeningCommitment(bytes32 policyHash, bytes32 identityHash, bytes32 salt) public pure returns (bytes32) {
         return keccak256(abi.encode(policyHash, identityHash, salt));
     }