@pvium/p2id-core 0.1.2 → 0.1.3

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();
@@ -111,8 +104,7 @@ contract PviumVerifier is IP2IDVerifier {
     }
 
     /// @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 +119,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));
     }

package/contracts/interfaces/IP2IDPolicy.sol

@@ -2,26 +2,11 @@
 pragma solidity ^0.8.27;
 
 /// @title IP2IDPolicy
-/// @notice Everything about P2ID vaults that is expected to evolve lives behind this interface,
-///         so it can change without changing vault bytecode (and therefore without moving any
-///         P2ID address). The vault factory points at one policy and can replace it only through
-///         a timelock; every vault consults the factory's current policy on each call.
-///
-///         What a policy decides, and the limits the vault enforces on it:
-///         - which verifiers deposits may be funded under and claimed through. Gating is the one
-///           thing a policy can use to stop claims (by disallowing a verifier), which freezes
-///           claims under it but never moves funds; refunds never consult the policy.
-///         - the protocol fee on payouts, in basis points. The vault caps it at its own
-///           MAX_FEE_BPS, fixes a deposit's rate when the deposit is made, never charges it on
-///           refunds, and treats a failing quote as no fee.
-///         - how accrued fees are distributed. Fees accrue in each vault per (verifier, token);
-///           anyone can have a vault hand them to the policy (withdrawFees), which pulls them and
-///           splits them however it chooses, e.g. between a verifier's operator and the protocol.
-///
-///         Launch policy: an owner-managed verifier allowlist and no fee. Permissionless,
-///         stake-based verifier registration and fees are later policies.
+/// @notice Verifier approval, fee quotation and fee distribution callbacks used by P2IDVault.
+/// @dev P2IDVault caps fee quotes, stores rates on funded deposits and quotes untracked funds at
+///      sweep time. It skips policy approval for claims through the current default verifier.
 interface IP2IDPolicy {
-    /// @notice Whether deposits may be funded under, and claimed through, `verifier`.
+    /// @notice Approval used for funding and for claims through a non-default verifier.
     function isVerifierAllowed(address verifier) external view returns (bool);
 
     /// @notice Fee on paying out `token` claimed through `verifier`, in basis points. Quoted when a
@@ -31,8 +16,7 @@ interface IP2IDPolicy {
     /// @notice Called by a vault holding fees earned through `verifier`. For an ERC-20 the vault
     ///         first approves this policy for exactly `amount`: pull the tokens (transferFrom the
     ///         caller) and distribute them; whatever is not pulled stays accrued in the vault, and
-    ///         the allowance is reset afterwards. Pulling from msg.sender makes the amount
-    ///         self-verifying: a caller that is not a vault can only give away its own tokens.
+    ///         the allowance is reset afterwards.
     ///         For the native coin (token == address(0)) the vault sends `amount` as msg.value
     ///         instead, and all of it counts as distributed.
     function distributeFee(address verifier, address token, uint256 amount) external payable;

package/contracts/interfaces/IP2IDVault.sol

@@ -4,10 +4,8 @@ pragma solidity ^0.8.27;
 import {IP2IDVerifier} from "./IP2IDVerifier.sol";
 
 /// @title IP2IDVault
-/// @notice A vault holding ERC-20 tokens and the native coin for one identity until its owner
-///         proves it and sweeps. The native coin is the token address(0) in every function.
-///         Every deposit names the verifier whose proofs can release it; the factory's policy
-///         decides which verifiers are allowed and what (capped) fee applies.
+/// @notice Deposit funding, claims, refunds and accounting for one identity commitment.
+///         Token address(0) denotes native coin. Each deposit records its verifier and fee rate.
 interface IP2IDVault {
     /// @dev Field order packs into 5 storage slots:
     ///      [funder, fundedAt, consumed] [token, refundWindow] [verifier, feeBps] [amount] [constraint].
@@ -25,8 +23,7 @@ interface IP2IDVault {
     }
 
     // ------------------------------------------------------------------ events
-    // Every deposit is Funded once and then either Refunded (by its funder) or Claimed by a sweep.
-    // Sweeps also emit one aggregate event with the net amount paid and the fee.
+    // Funding emits Funded; consumption emits Refunded or Claimed. Sweeps emit aggregate amounts.
 
     /// @notice A deposit was recorded via fund()/fundWith()/fundFor().
     /// @param ref Opaque application reference; zero means absent. Emitted only, not stored or enforced as unique.
@@ -35,15 +32,15 @@ interface IP2IDVault {
     event Refunded(uint256 indexed depositId, address indexed funder, address indexed token, uint256 amount);
     /// @notice A deposit was paid out by a sweep: `amount` gross, of which `fee` accrued as a fee.
     event Claimed(uint256 indexed depositId, address indexed to, uint256 amount, uint256 fee);
-    /// @notice A proof newer than any seen under `verifier` set that verifier's owner wallet; older proofs are now refused.
+    /// @notice The owner cache was set or revalidated under the verifier's current revision.
     event OwnerRefreshed(address indexed verifier, address indexed owner, uint64 iat);
-    /// @notice Default-bucket funds under `verifier` were paid to its owner wallet (`amount` net of `fee`).
+    /// @notice Default sweep result, including eligible untracked funds; amount is net of fee and may be zero.
     event Swept(address indexed verifier, address indexed token, uint256 amount, uint256 fee, address indexed to, uint256 depositsConsumed);
     /// @notice Funds from a constrained bucket were paid to the wallet the proof resolved to (`amount` net of `fee`).
     event SweptBucket(address indexed verifier, bytes32 indexed constraint, address indexed token, uint256 amount, uint256 fee, address to, uint256 depositsConsumed);
     /// @notice A fee accrued for `verifier`; it stays in the vault until withdrawFees() hands it to the policy.
     event FeeAccrued(address indexed verifier, address indexed token, uint256 amount);
-    /// @notice The policy pulled `amount` of accrued fees to distribute.
+    /// @notice Amount deducted from accrued fees after policy distribution, via token pull or native transfer.
     event FeesDistributed(address indexed verifier, address indexed token, uint256 amount, address policy);
 
     // setup (factory only, once)
@@ -56,7 +53,7 @@ interface IP2IDVault {
     /// @notice Fund under any verifier the factory's policy allows.
     /// @param ref Opaque application reference emitted in Funded; bytes32(0) for none.
     function fundWith(address verifier, address token, uint256 amount, bytes32 constraint, uint64 refundWindow, bytes32 ref) external payable returns (uint256 depositId);
-    /// @notice Factory-only: record a deposit owned by `funder`; tokens are pulled from the factory.
+    /// @notice Factory-only: record a deposit for `funder`; pull ERC-20 from the factory or receive native msg.value.
     /// @param ref Opaque application reference emitted in Funded; bytes32(0) for none.
     function fundFor(address funder, address verifier, address token, uint256 amount, bytes32 constraint, uint64 refundWindow, bytes32 ref) external payable returns (uint256 depositId);
     function refund(uint256 depositId) external;
@@ -66,9 +63,16 @@ interface IP2IDVault {
     ///         if the proof is newer than anything seen under it, and retires older proofs.
     function refreshProof(address verifier, bytes calldata proof) external;
     function refreshProofAndSweep(address verifier, bytes calldata proof, address token, uint256 depositCountLimit) external returns (uint256 amount, uint256 consumed);
+    /// @notice Apply a proof the vault's own proxy has already verified (msg.sender must be this
+    ///         address): the freshness, revision and owner-cache rules of refreshProof without
+    ///         re-verifying. Reverts unless `wallet` is the recorded owner under `verifier` afterwards.
+    ///         Returns its own selector as acknowledgement so the proxy rejects empty fallbacks.
+    ///         The acknowledgement checks compatibility; implementations remain trusted to apply the result.
+    function acceptOwnerProof(address verifier, address wallet, uint64 iat) external returns (bytes4);
 
     // claiming (amounts returned are net of fees)
-    /// @notice Sweep `verifier`'s default bucket to its owner; the default verifier's sweep also takes untracked funds.
+    /// @notice Sweep a page of the verifier's default bucket to its cached owner. Eligible untracked
+    ///         funds are included for the current default verifier when its cache meets the cross-default floor.
     function sweep(address verifier, address token, uint256 depositCountLimit) external returns (uint256 amount, uint256 consumed);
     function sweepUntracked(address token) external returns (uint256 amount);
     function sweepDeposits(address verifier, address token, uint256[] calldata depositIds) external returns (uint256 amount);
@@ -83,9 +87,11 @@ interface IP2IDVault {
     /// @notice P2ID vault interface version implemented by this contract.
     function p2idVersion() external pure returns (string memory);
     function MAX_FEE_BPS() external view returns (uint16);
+    /// @notice Record cap for cursor-based sweeps; a zero or above-cap depositCountLimit uses this value.
+    function MAX_SWEEP_PAGE() external view returns (uint256);
     /// @notice address(0): the token address standing for the native coin.
     function NATIVE() external view returns (address);
-    /// @notice keccak256 of the address scheme this vault was issued under, e.g. keccak256("pvium.vault.v1").
+    /// @notice Namespace value supplied at initialization; not used to recompute this vault's address.
     function nsHash() external view returns (bytes32);
     function factory() external view returns (address);
     function policy() external view returns (address);
@@ -96,17 +102,18 @@ interface IP2IDVault {
     function untrackedProofIat() external view returns (uint64);
     function saltCommitment() external view returns (bytes32);
     function depositCount() external view returns (uint256);
-    function bucketDepositIds(address verifier, bytes32 constraint, address token) external view returns (uint256[] memory);
+    /// @notice A page of the bucket's deposit ids: up to `limit` from `offset` (limit 0 = all from `offset`).
+    function bucketDepositIds(address verifier, bytes32 constraint, address token, uint256 offset, uint256 limit) external view returns (uint256[] memory);
     function bucketDepositCount(address verifier, bytes32 constraint, address token) external view returns (uint256);
-    /// @notice Whether `funder` has funded under `constraint`, and which deposit. A funder can use a
-    ///         constraint once (refunded or claimed, it stays used), so a signature over it releases
-    ///         at most one of their deposits. Funders must make constraints unique, e.g. by salting.
+    /// @notice Deposit recorded for a nonzero constraint and funder in this vault. The record persists
+    ///         after a refund or claim and prevents the same funder from reusing that constraint here.
     function constraintDeposit(bytes32 constraint, address funder) external view returns (bool used, uint256 depositId);
     function bucketTotal(address verifier, bytes32 constraint, address token) external view returns (uint256);
     function trackedTotal(address token) external view returns (uint256);
     function feesOwed(address verifier, address token) external view returns (uint256);
     function feesOwedTotal(address token) external view returns (uint256);
-    /// @notice Gross amount `sweep(verifier, token, 0)` would release now, before fees.
+    /// @notice Total default-bucket amount plus eligible untracked funds, before fees.
+    ///         Does not apply the sweep page limit or validate default-bucket claimability.
     function sweepable(address verifier, address token) external view returns (uint256);
     function untrackedBalance(address token) external view returns (uint256);
 }

package/contracts/interfaces/IP2IDVaultProxy.sol

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.27;
+
+/// @title IP2IDVaultProxy
+/// @notice A P2ID proxy with creation code fixed for its deployed factory. Its upgradeTo entry
+///         point requires an identity proof and a registered target. Delegated implementations
+///         are trusted with all proxy storage, including the implementation slot.
+interface IP2IDVaultProxy {
+    /// @notice ERC-1967 upgrade event.
+    event Upgraded(address indexed implementation);
+
+    /// @notice The factory that deployed this proxy and whose registry bounds its implementations.
+    function factory() external view returns (address);
+    /// @notice The implementation used for delegated calls; proxy-defined selectors take precedence.
+    function implementation() external view returns (address);
+    /// @notice The wallet and issue time of the proof behind the last upgrade (zero before the first).
+    ///         Later upgrades need a proof at least this recent; an equal time only for the same wallet.
+    ///         Delegated code can overwrite this record; upgradeTo ignores a record beyond its future-time bound.
+    function lastUpgrade() external view returns (address wallet, uint64 iat);
+    /// @notice Move this vault to `newImplementation`, which the factory must have registered.
+    ///         `proof` is verified through the factory's default verifier for `identityHash` (the
+    ///         identity this address was derived from); the wallet it resolves to must be the caller,
+    ///         and its issue time must not exceed block.timestamp + 15 minutes or fall below lastUpgrade.
+    ///         It must also meet the current implementation's latestProofIat for that verifier and
+    ///         untrackedProofIat; failed, malformed or excessively future-dated floor reads count as zero.
+    ///         This call writes the implementation slot and lastUpgrade record, then calls
+    ///         acceptOwnerProof through the new implementation without verifying the proof again.
+    ///         Hook failure reverts the entire upgrade. P2IDVault's hook requires the proven wallet
+    ///         to be the resulting cached owner, rejecting conflicting equal-time wallet proofs.
+    ///         The proxy requires the hook selector as a canonical 32-byte ABI acknowledgement;
+    ///         absent, malformed or incorrect acknowledgements revert the entire upgrade.
+    ///         After the hook, the implementation must still match the target, owner(verifier)
+    ///         must report the proven wallet, and latestProofIat(verifier) must be at least iat.
+    ///         Nested upgradeTo calls revert while an upgrade is running.
+    /// @dev Getters run through delegated code and cannot establish that an implementation is safe.
+    ///      This entry point performs no separate initialization or storage-migration call.
+    function upgradeTo(bytes32 identityHash, address newImplementation, bytes calldata proof) external;
+}

package/contracts/interfaces/IP2IDVerifier.sol

@@ -2,8 +2,7 @@
 pragma solidity ^0.8.27;
 
 /// @title IP2IDVerifier
-/// @notice Use-case-agnostic identity verification: given a proof, return the wallet the proven
-///         identity resolves to. Optionally also verify a funding constraint.
+/// @notice Resolve an identity proof to a wallet and issue time, with optional constraint evidence.
 interface IP2IDVerifier {
     /// @notice A funding constraint and the evidence that it is satisfied.
     /// @param commitment bytes32(0) = no constraint; otherwise the commitment a deposit was funded with.
@@ -15,9 +14,7 @@ interface IP2IDVerifier {
         bytes signature;
     }
 
-    /// @param identityHash The identity the caller expects the proof to be for (e.g. the vault's
-    ///                     commitment). Proofs are public once used on-chain, so the caller MUST
-    ///                     pin the identity rather than trust whatever the submitted proof proves.
+    /// @param identityHash Expected identity commitment that the implementation must match against the proof.
     /// @param proof        Opaque identity proof; the implementation defines the encoding.
     /// @param constraint   Skipped when `constraint.commitment == bytes32(0)`.
     /// @return wallet Wallet associated with the proven identity (never address(0)).
@@ -30,15 +27,14 @@ interface IP2IDVerifier {
         Constraint calldata constraint
     ) external view returns (address wallet, uint64 iat);
 
-    /// @notice Whether this verifier can ever satisfy a non-zero constraint. Vaults refuse
-    ///         constrained deposits under a verifier that returns false (or does not implement
-    ///         this), so a payer cannot lock funds behind a condition nobody can meet.
+    /// @notice Whether this verifier currently supports nonzero constraints. P2IDVault requires
+    ///         a successful true response when funding a constrained deposit; this does not establish
+    ///         that any particular commitment can be satisfied.
     function supportsConstraints() external view returns (bool);
 
-    /// @notice Changes (increments) whenever proofs this verifier accepted before may no longer be
-    ///         trusted, e.g. a signing key was revoked. A vault caches the wallet a proof resolved
-    ///         to and pays it without re-verifying; it discards that cache when the revision moved,
-    ///         so revoking a key also revokes what was proven under it. Return a constant if
-    ///         nothing this verifier trusts can ever be revoked.
+    /// @notice Cache revision. Implementations must increment it when previously accepted identity
+    ///         proofs may no longer be trusted, or return a constant if trust cannot be revoked.
+    /// @dev P2IDVault rejects cached-owner claims when this differs from the stored revision, and
+    ///      rejects cached-owner claims and proof updates when the revision cannot be read.
     function revision() external view returns (uint64);
 }

package/contracts/interfaces/IP2IdVaultFactory.sol

@@ -2,30 +2,57 @@
 pragma solidity ^0.8.27;
 
 /// @title IP2IdVaultFactory
-/// @notice Deploys one P2IDVault per identity at an address anyone can derive offline from the
-///         identity hash, and points every vault at the current policy and default verifier.
+/// @notice Vault proxy deployment, address derivation, funding and shared configuration views.
 interface IP2IdVaultFactory {
     event VaultDeployed(bytes32 indexed identityHash, address indexed vault);
+    event ImplementationProposed(address indexed implementation, uint64 eta);
+    event ImplementationProposalCancelled(address indexed implementation);
+    event ImplementationRegistered(address indexed implementation);
+    event ImplementationDeployed(address indexed implementation, bytes32 creationCodeHash);
+    event ImplementationDefaultProposed(address indexed implementation, bool makeDefault, uint64 eta);
+    event DefaultImplementationActivated(address indexed implementation);
+    event ImplementationRevoked(address indexed implementation);
 
     /// @notice P2ID factory interface version implemented by this contract.
     function p2idVersion() external pure returns (string memory);
 
-    // ---- what vaults consult on every call; both change only through a timelock ----
-    /// @notice The IP2IDPolicy deciding which verifiers are allowed and what (capped) fee applies.
+    // ---- shared configuration ----
+    /// @notice Policy address used for verifier approval, fee quotes and fee distribution.
     function policy() external view returns (address);
     /// @notice Verifier used when a payer does not choose one, and the one bare transfers are claimed through.
     function defaultVerifier() external view returns (address);
 
+    // ---- vault implementations ----
+    /// @notice The implementation every newly deployed vault proxy starts on.
+    function baseImplementation() external view returns (address);
+    /// @notice Whether the implementation is registered as an upgrade target; other upgrade checks also apply.
+    function isRegisteredImplementation(address implementation) external view returns (bool);
+
+    function initialImplementation() external view returns (address);
+    function implementationFor(bytes32 creationCodeHash) external view returns (address);
+    /// @notice Deploy full creation code and propose registration; makeDefault applies after the delay.
+    function deployVaultImplementation(bytes memory creationCode, bool makeDefault) external returns (address);
+    function proposeDefaultImplementation(address implementation) external;
+
+    // ---- address derivation constants ----
+    /// @notice Namespace value supplied to the factory constructor and passed to vault initialization.
+    function nsHash() external view returns (bytes32);
+    /// @notice Proxy creation-code hash used with this factory's address and an identityHash for CREATE2 derivation.
+    function initCodeHash() external pure returns (bytes32);
+    /// @notice Refund-window bounds passed to new vaults during initialization.
+    function minRefundWindow() external view returns (uint64);
+    function maxRefundWindow() external view returns (uint64);
+
     // ---- vaults ----
     /// @notice The vault address for `identityHash`, deployed or not:
-    ///         `keccak256(0xff ‖ factory ‖ identityHash ‖ keccak256(P2IDVault creationCode))`.
+    ///         Low 160 bits of `keccak256(0xff || factory || identityHash || initCodeHash())`.
     function vaultFor(bytes32 identityHash) external view returns (address);
     function isDeployed(bytes32 identityHash) external view returns (bool);
     /// @notice Deploy the vault for `identityHash`; returns the existing one if already deployed.
     function deploy(bytes32 identityHash) external returns (address vault);
     /// @notice Deploy if needed, then fund under the default verifier on the caller's behalf
-    ///         (caller keeps the refund right). ERC-20: approve this factory once to pay any
-    ///         identity. Native coin: token = address(0), send `amount` as msg.value.
+    ///         (caller is recorded as funder). ERC-20: approve this factory for the requested amount.
+    ///         Native coin: token = address(0), send `amount` as msg.value.
     /// @param ref Opaque application reference forwarded to the vault's Funded event; bytes32(0) for none.
     function fund(
         bytes32 identityHash,

package/contracts/interfaces/IPviumIdentity.sol

@@ -2,19 +2,17 @@
 pragma solidity ^0.8.27;
 
 /// @title IPviumIdentity
-/// @notice Verify a Pvium attestation on chain: "identity X and wallet W belong to the same
-///         Privy user". Every function reverts unless the proof is valid, was made from a token
-///         signed by one of the accepted keys, and binds exactly the values given. The return value is
-///         when Privy issued that token (unix seconds); freshness policy is the caller's.
+/// @notice Attestation verification and signer/version views exposed by PviumIdentity.
+///         verifyIdentity checks the supplied identity type, identity hash and wallet hash.
 interface IPviumIdentity {
     /// @notice Circuit version this deployment verifies. Attestations state theirs; use the matching deployment.
     function circuitVersion() external view returns (uint16);
-    /// @notice Whether tokens signed by this P-256 key are accepted. Keys are added with 7 days' public notice.
+    /// @notice Whether this P-256 key belongs to the deployment's current accepted signer set.
     function isSignerKey(uint256 x, uint256 y) external view returns (bool);
 
     /// @notice Verify that the proof binds exactly this identity and this wallet.
-    /// @dev Both are passed as hashes (P2IDHash on chain, or the SDK's identityHash), so the raw
-    ///      identity never appears in calldata.
+    /// @dev The expected identity and wallet are supplied as hashes. The function does not impose
+    ///      an age limit on the attestation.
     /// @param identityType Identity type id: 0 email, 3 twitter, 5 github, … (see P2IDHash)
     /// @param identityHash P2IDHash.identityHash(identityType, value)
     /// @param walletHash   P2IDHash.walletHash(wallet): an address, or a string for a non-EVM wallet

package/contracts/lib/P2IDHash.sol

@@ -2,10 +2,10 @@
 pragma solidity ^0.8.27;
 
 /// @title P2IDHash
-/// @notice The identity commitment exactly as circuit/src/main.nr computes it:
+/// @notice Identity commitment:
 ///         sha256("p2id.identity.v1" || identityType || normalize(value)).
-///         `normalize` ASCII-lowercases every type except phone and wallet, and lowercases
-///         `0x…` (EVM, hex) wallet addresses; base58 (Solana) addresses are untouched.
+///         Normalization ASCII-lowercases non-phone, non-wallet values. Wallet values are
+///         lowercased only when they start with lowercase `0x`; other wallet strings are unchanged.
 library P2IDHash {
     bytes internal constant PREFIX = "p2id.identity.v1";
     uint8 internal constant PHONE = 1;
@@ -27,7 +27,7 @@ library P2IDHash {
         return sha256(abi.encodePacked(PREFIX, WALLET, toLowerHex(wallet)));
     }
 
-    /// @notice Commitment for a wallet on any chain, given as Privy stores it (e.g. base58).
+    /// @notice Wallet-string commitment using type 12, with identityHash's normalization and length checks.
     function walletHash(string memory wallet) internal pure returns (bytes32) {
         return identityHash(WALLET, bytes(wallet));
     }
@@ -48,7 +48,7 @@ library P2IDHash {
         return out;
     }
 
-    /// @dev "0x" + 40 lowercase hex chars, the form the circuit hashes an EVM address in.
+    /// @dev Encode an address as "0x" followed by 40 lowercase hexadecimal characters.
     function toLowerHex(address a) internal pure returns (bytes memory out) {
         bytes16 digits = "0123456789abcdef";
         out = new bytes(42);

package/dist/cjs/p2idConstants.js

@@ -5,10 +5,10 @@ exports.P2ID_SCHEME = exports.P2ID_SCHEMES = void 0;
 exports.P2ID_SCHEMES = {
     "pvium.vault.v1": {
         "identityDomain": "p2id.identity.v1",
-        "vaultInitCodeHash": "0x59c2f7f1e9725340e25a45b122fae7d1e9cbd9c7b00dba6215ebaa67cfb691ef",
+        "vaultInitCodeHash": "0x4c76d638c6e156d8a95617576f1dcac6189257696607110346ba4f5fe2932ca6",
         "factories": {
             "production": null,
-            "sandbox": "0xd1DEa4e8911955DAD961B643AFdE6Ab34d9Bd371"
+            "sandbox": "0x5d173035d5Ae0b67a521FbFE72bDe43C96a0080A"
         }
     }
 };

package/dist/esm/p2idConstants.d.ts

@@ -18,10 +18,10 @@ export interface P2IDScheme {
 export declare const P2ID_SCHEMES: {
     readonly "pvium.vault.v1": {
         readonly identityDomain: "p2id.identity.v1";
-        readonly vaultInitCodeHash: "0x59c2f7f1e9725340e25a45b122fae7d1e9cbd9c7b00dba6215ebaa67cfb691ef";
+        readonly vaultInitCodeHash: "0x4c76d638c6e156d8a95617576f1dcac6189257696607110346ba4f5fe2932ca6";
         readonly factories: {
             readonly production: null;
-            readonly sandbox: "0xd1DEa4e8911955DAD961B643AFdE6Ab34d9Bd371";
+            readonly sandbox: "0x5d173035d5Ae0b67a521FbFE72bDe43C96a0080A";
         };
     };
 };

package/dist/esm/p2idConstants.js

@@ -2,10 +2,10 @@
 export const P2ID_SCHEMES = {
     "pvium.vault.v1": {
         "identityDomain": "p2id.identity.v1",
-        "vaultInitCodeHash": "0x59c2f7f1e9725340e25a45b122fae7d1e9cbd9c7b00dba6215ebaa67cfb691ef",
+        "vaultInitCodeHash": "0x4c76d638c6e156d8a95617576f1dcac6189257696607110346ba4f5fe2932ca6",
         "factories": {
             "production": null,
-            "sandbox": "0xd1DEa4e8911955DAD961B643AFdE6Ab34d9Bd371"
+            "sandbox": "0x5d173035d5Ae0b67a521FbFE72bDe43C96a0080A"
         }
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pvium/p2id-core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "P2ID protocol core: identity types and hashing, chain-agnostic P2ID address derivation, and the Solidity sources",
   "license": "MIT",
   "type": "module",