Fileverse Private Social ZKovery Contracts

Overview

This repository provides a framework for privacy-enhancing and decentralized social recovery of user accounts on Fileverse Apps e.g., as ddocs.new and dsheets.new. The framework leverages advanced cryptographic primitives, such as Semaphore's zero-knowledge (ZK) proof system, to allow account holders to assign anonymous "guardians" (i.e., private set members) with the ability to collectively recreate account keys and help in the recovery of an account. These guardians' identities (e.g., email or wallet address) are kept completely private as guardians generate a local (i.e., on their browser) proof that they belong to a given secret recovery set. This makes the recovery process both secure and privacy-enhancing.

To ensure that the recovery process is not dependent on third-parties, including Fileverse itself, the social recovery process leverages smart contracts that are available at all times to the account holder and their guardians. In other words, the recovery process is serverless and only dependent on the guardians availability and the availability of the network (Gnosis) on which the contracts are deployed. Gnosis is a permissionless and censorship-resistant network that ensures you will always be able to perform your recovery process and retrieve your account data in a self-sovereign manner. All recovery operations are fully compatible with gasless meta-transactions (via ERC2771) and make use of secure, two-step ownership transfers.

At the heart of these designs is deep integration with Semaphore contracts, leveraging zero-knowledge (ZK) proof systems to manage recovery groups as private, cryptographically secure sets.

The two primary contracts are:

Contracts Overview

1. Recovery.sol

The Recovery contract orchestrates recovery sets for robust key/social recovery, grounded in the privacy guarantees of Semaphore-based zero-knowledge sets ("zk sets"). Guardians are not just addresses, they are represented by unique identity commitments registered in Semaphore groups, ensuring maximum privacy and security. Guardians can securely approve recoveries via ZK proofs without ever revealing which individual approved –only that a valid group member did approve.

Main Features:

• Guardian Management (Semaphore Integration): Add, edit, and remove guardians as Semaphore identity commitments. All guardian actions are mediated through their inclusion in Semaphore zk groups, giving privacy-enhancing set membership for social recovery.
• Threshold Recovery: Specify the number of guardian approvals (the "threshold") needed for a successful recovery, with approval proven cryptographically via ZK proofs.
• Recovery Process:
  • Setup: Create ZK-enabled recovery sets with custom metadata and associated Semaphore group IDs.
  • Accept/Decline: Guardians accept their role, introducing their identity commitment to the Semaphore group for private set management.
  • Trigger: Start a recovery, which only the required subset of guardians (demonstrating group membership via Semaphore proofs) can approve.
  • Approval/Rejection: Guardians securely submit approvals or rejections by providing their zero-knowledge proofs and optional (IPFS) shards or off-chain attestations.
• Meta-Transactions: Full support for gasless operations using ERC2771Context (Trusted Forwarder).
• Blocking: Temporary blocking of all recovery operations by the identity.

Key Data Structures:

• RecoverySetMetadata: Tracks group label, associated Semaphore group ID, threshold, and additional details.
• Guardian: Guardian's address, identity commitment (used in ZK proofs/Semaphore), and associated metadata.
• TriggerState: State tracker for an ongoing recovery, capturing participant proofs and states.

Events:

• Rich event system, including: RecoverySetCreated, GuardianAccepted, RecoveryTriggered, RecoveryApproved, RecoveryRejected, RecoverySetUpdated, etc.

2. RecoveryRegistry.sol

The RecoveryRegistry contract acts as the global on-chain registry mapping each identity to its corresponding Recovery contract.

Main Features:

• Deployment/Minting: Solely an identity's agent can deploy or assign a Recovery contract to that identity. Deployments inherently tie the recovery process to Semaphore ZK groups for guardian management.
• Mappings: Fast lookups between identity addresses and their assigned Recovery contracts.
• Forwarder Management: Admin (owner) can set the ERC2771 trusted forwarder for gasless meta-transactions.
• Meta-Transactions: All public methods are compatible with the trusted forwarder.

Events:

• Emits Mint (when a new Recovery module is assigned to an identity).

Emphasis on Semaphore & Zero-Knowledge Sets

• Semaphore contracts (see Semaphore Docs) are core to both the logic and privacy properties of these recovery contracts.
• Guardian sets are represented as zk sets managed by Semaphore: Only guardians who can produce valid ZK proofs (proving group membership) can interact with sensitive flows like approvals, enabling privacy-enhancing social recovery at scale.
• The use of zero-knowledge proofs means no on-chain or publicly observable mapping exists between guardians and recoveries—only membership in the Semaphore set is required for all approvals.

Usage

• To setup a recovery module:
  Use RecoveryRegistry.mint(identityAddress) to deploy a Recovery contract linked to your identity. This starts the process of onboarding a Semaphore group for guardian ZK approvals.

• To manage guardians (via zk sets):
  Use methods in Recovery:

  • setupRecovery(label, threshold, metadata, guardians, commitments): Onboard guardians as Semaphore group members by their identity commitments.
  • updateRecoverySet, flush, etc.

• To trigger a recovery:
  Use Recovery.triggerRecovery(id, triggeredBy)
  Guardians approve via approveRecovery by submitting their Semaphore ZK proof, or can reject/provide external data as necessary.

• Access Control:
  Only the identity owner or their agent manages zk sets; only guardians (valid Semaphore group members) can approve/reject. All actions are subject to strict ZK-based membership checks.

Security Features

• Semaphore Layer: Guardianship and approvals are fully managed by ZK sets, protecting participant privacy and enabling scalable, trustless group-based recovery.
• OpenZeppelin Ownable2Step: Secure, two-step contract ownership transfer.
• ERC2771Context: Meta-transaction (gasless) flows built-in.
• No Approver Leak: Thanks to zk proofs, no public guardian lists or approver "leakage"—all sensitive flows occur via on-chain ZK verification.

Events & Error Codes

Refer to the contract code for all event definitions and error handling conventions, including semantic revert reasons like "FV200" (duplicate registry) and specific error codes for ZK validation failures.

License

• Recovery.sol: GPL-3.0
• RecoveryRegistry.sol: GPL-3.0

Further Reading

• Semaphore Documentation
• OpenZeppelin Contracts

Acknowledgments

This ZK Social Recovery approach is built on top of the work done by the Privacy Stewards of Ethereum on the semaphore protocol, to enable new use cases. We would like to thank their team for their support and quick turn-around in deploying the Semaphore smart contracts on Gnosis to enable this work! Zero-knowledge proofs and smart contracts have the potential to fundamentally transform online account and identity management, strengthening many of the activities people rely on every day across the Internet. At Fileverse, our work is focused on making these advances in security, privacy, and self-sovereignty accessible to the widest possible audience—so everyone can benefit from a more secure and user-controlled digital future.