Fileverse Floppy Contracts

This repository contains a set of Solidity smart contracts for managing "Floppies"—tokenized disks with access control—and specialized access management patterns. The contracts are meant for experimentation with Storage Floppys, manager modules, and extensions for Semaphore-compatible group/identity management.

Overview

Floppy implements a registry of "FloppyDisks"—unique access groups with capacity limits, human-readable identifiers, and zero-knowledge proof verification. Each floppy integrates with the Semaphore protocol to enable privacy-preserving claims and membership verification.

Architecture

The system uses a three-tier permission model:

• Owner: Controls floppy creation, metadata updates, and permission management
• Managers: Per-floppy addresses authorized to grant access to identity commitments
• Operators: Trusted validators that process zero-knowledge proof claims

This separation enables flexible, extensible access control patterns through custom manager contracts.

Core Contracts

Floppy.sol

The main registry contract managing FloppyDisk lifecycle and access control.

Key Features:

• Dual indexing system (numeric IDs + human-readable shortCodes)
• Capacity-limited access groups with configurable maxCount
• Semaphore integration for zero-knowledge membership proofs
• Per-floppy manager delegation for flexible access policies
• Operator system for trusted claim verification
• Comprehensive event emission for off-chain indexing

Core Functions:

• addFloppy() - Create new floppy with capacity limits and initial managers
• updateFloppy() - Modify floppy metadata and capacity (owner only)
• grantFloppy() - Add identity commitment to floppy group (managers only)
• claimFloppy() - Validate ZK proof and process claim (operators only)
• verifyFloppyProof() - View function to check proof validity
• getFloppyByShortCode() - Lookup floppy by human-readable code

Access Control:

• Inherits OpenZeppelin Ownable2Step for secure ownership transfers
• Per-floppy manager mapping enables isolated permissions
• Global operator mapping for claim processing authorization

Events:

• FloppyCreated - New floppy registration
• FloppyUpdated - Metadata or capacity changes
• FloppyManagerAdded/Removed - Manager permission changes
• FloppyOperatorAdded/Removed - Operator authorization changes
• FloppyGranted - Identity commitment granted access
• FloppyClaimed - ZK proof validated and claim processed

SimpleManager.sol

Minimal manager implementation demonstrating the extension pattern.

Purpose: Reference implementation showing how external contracts can implement custom logic for granting floppy access.

Key Features:

• Owner-controlled access granting
• ShortCode-based floppy lookup
• Custom event emission for tracking
• Clean interface to core Floppy contract

Extension Possibilities:

Custom managers can implement:

• Payment gates (ETH/token requirements)
• Time-based access windows
• External condition checks (NFT ownership, DAO membership)
• Batch granting operations
• Allowlist/denylist logic

Supporting Interfaces

IFloppy.sol Minimal interface exposing core floppy functionality for external integrations:

• Floppy lookup by ID or shortCode
• Access granting function
• Claim processing function
• FloppyDisk struct definition

IHub.sol Interface for external hub/registry integration:

• Organization registration
• Trust relationship management
• Semaphore deployed contracts reference

---

Getting Started

Installation

npm install

Compile Contracts

npx hardhat compile

Run Tests

npx hardhat test

Deployment

Deploy using Hardhat Ignition modules:

npx hardhat ignition deploy ignition/modules/Floppy.ts

Or customize deployment parameters:

• Semaphore contract address
• Admin address
• Initial floppy configurations (shortCode, maxCount, diskSpace, metadataURI)
• Manager addresses

How It Works

1. Setup Phase

The owner deploys the Floppy contract with a Semaphore instance:

Floppy floppy = new Floppy(semaphoreAddress, adminAddress);

2. Floppy Creation

The owner creates a new floppy with capacity limits and authorized managers:

floppy.addFloppy(
    "EVENT-2024",      // shortCode: human-readable identifier
    500,               // maxCount: maximum members allowed
    10000,             // diskSpace: metadata field (storage quota)
    "ipfs://...",      // metadataURI: off-chain metadata
    [managerAddress]   // managers: addresses authorized to grant access
);

This automatically creates a Semaphore group for privacy-preserving membership.

3. Granting Access

Managers grant access by adding identity commitments to the floppy:

// User generates identity commitment off-chain using Semaphore SDK
uint256 identityCommitment = generateCommitment(secret);

// Manager grants access
floppy.grantFloppy(floppyId, identityCommitment);

4. Claiming with Zero-Knowledge Proofs

Users prove membership without revealing their identity:

// User generates ZK proof off-chain
SemaphoreProof memory proof = generateProof(
    identity,
    groupId,
    message,
    scope
);

// Operator validates and processes claim
floppy.claimFloppy(floppyId, proof);

The nullifier in the proof prevents double-claiming while maintaining privacy.

Technical Stack

• Solidity 0.8.28: Latest language features and optimizations
• Semaphore Protocol v4: Production-ready ZK-SNARK proof system
• OpenZeppelin Contracts: Industry-standard access control and utilities
• Hardhat: Modern development and testing framework
• Viem: Type-safe Ethereum interactions

Security Considerations

• Floppy uses Ownable2Step for secure ownership transfers
• Semaphore handles nullifier tracking to prevent double-claims
• Capacity limits prevent unlimited growth
• Manager isolation ensures per-floppy permission boundaries
• Comprehensive event emission enables monitoring and auditing

Contributing

PRs and feedback welcome! Please ensure all tests pass before submitting.

---

License: MIT