privacy-pump-keeper-reference

Maturity: Reference state machine
Supported network: Deterministic local simulation
Audit status: Publication is not an audit. No external audit is claimed.

Non-custodial reference state machine for Privacy Pump fee settlement.

Purpose

Models settlement readiness and state transitions without keys, transactions, RPC, HTTP triggers, or production destinations.

Scope

• Non-signing design
• Threshold/time readiness
• Deterministic failure cases

Architecture

flowchart LR
  User[Wallet or integrator] --> Interface[Public interface]
  Interface --> Boundary[Privacy Pump trust boundary]
  Boundary --> Chain[Solana or local reference]
  Boundary -. metadata exposure .-> Limits[Documented limitations]

Loading

See ARCHITECTURE.md for component boundaries and assumptions.

Current security status

• Experimental or reference material; not mainnet-ready.
• The inspected devnet programs are upgradeable and shared one upgrade authority at the publication audit date.
• Factory and relayer are distinct protocol roles, but a deployment may configure one signer for both.
• Production signer topology is intentionally not published.
• The ZK Pool vault-creation fee receipt does not independently bind its signer named factory to the Private Vault config factory; that boundary is under review.
• The ZK verifier path is fail-closed by default and is not a complete production privacy system.
• Browser, RPC, relayer, database, Waku/Logos, and Arcium metadata each have separate privacy limitations.
• Custom cryptographic glue is not described as audited.

Read SECURITY.md before using any material.

Dependencies

• privacy-pump-zk-pool-reference

Local setup

Use deterministic fixtures and ephemeral local keys only. No production credentials, cloud accounts, private RPC endpoints, or real wallet relationships are required.

node scripts/policy-scan.mjs

Repository-specific build and test commands are documented when executable source is present. Placeholder repositories run documentation and policy checks only.

Roadmap

• Add model-based tests
• Pin settlement interface
• Review liveness assumptions

Related Privacy Pump repositories

• privacy-pump-zk-pool-reference

Known limitations

• Public content omits production relayer, access-control, KMS, Supabase service-role, keeper-signing, monitoring, and deployment implementations.
• Privacy depends on more than user-interface masking; metadata visible to wallets, RPCs, relayers, transports, and infrastructure remains relevant.
• Interfaces may change while the devnet architecture is stabilized.

Contributing

See CONTRIBUTING.md. Licensing is under review; see LICENSE_STATUS.md.