Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
156 lines (116 loc) · 4.25 KB

ARCHITECTURE.md

File metadata and controls

156 lines (116 loc) · 4.25 KB
Raw

Droptron Architecture

Droptron is a full-stack confidential token distribution product. It combines a Next.js workspace, TokenOps SDK flows, ERC-7984 confidential tokens, Supabase persistence, and a recipient claim portal.

System Overview

Operator wallet
  |
  v
Droptron workspace
  |
  |-- campaign setup
  |-- token selection
  |-- recipient validation
  |-- TokenOps operation modal
  |-- receipts and admin controls
  |
  v
TokenOps SDK + ERC-7984 token contracts
  |
  v
Zama-compatible confidential execution and decrypt paths

Recipient wallet
  |
  v
Droptron claim portal
  |
  |-- wallet-scoped eligibility lookup
  |-- allocation reveal
  |-- claim or vesting withdrawal

Main Components

Frontend

Location: frontend/

Responsibilities:

  • workspace onboarding and wallet access checks
  • campaign builder for disperse, airdrop, and vesting
  • distribution detail pages and operation modals
  • claim portal and recipient detail pages
  • wallet connection through RainbowKit and wagmi
  • contract reads/writes through viem and TokenOps SDK
  • Zama user decryption through the Zama FHE React SDK
  • premium loading and error states for network-dependent flows

TokenOps Integration

Droptron uses the @tokenops/sdk npm package for the confidential distribution primitives.

The integration covers:

  • confidential disperse execution
  • confidential airdrop clone deployment, funding, claim payload publishing, and recipient claims
  • confidential vesting manager creation, schedule creation, grant reveal, and recipient claiming
  • TokenOps role/admin surfaces where needed for recovery and operations

Data Layer

Location: supabase/migrations/

Supabase stores operational metadata:

  • workspace profile
  • campaign setup data
  • lifecycle status
  • token and network references
  • public contract addresses
  • transaction hashes and receipt URLs
  • TokenOps encrypted handle references
  • airdrop claim payload references and signatures
  • vesting manager addresses and vesting IDs

Supabase should not be treated as a plaintext allocation ledger. Allocation values should be encrypted, referenced by handles, or re-imported by the operator when needed.

Contracts

Location: hardhat/

The contract package contains Droptron's demo ERC-7984 token for Sepolia development and testing.

TokenOps protocol contracts provide the main distribution surfaces. Droptron's contract package is focused on the demo asset and deployment workflow rather than replacing TokenOps primitives.

Runtime Boundaries

Public Product State

The app may show:

  • campaign name and mode
  • token symbol and address
  • network
  • claim window or vesting timeline
  • public receipt link
  • contract addresses
  • operation status
  • recipient count

Private Product State

The app should avoid storing or permanently displaying:

  • plaintext recipient allocation amounts
  • plaintext vesting grant values
  • decrypted claim amounts
  • private balance values after the user hides them

Reveal is an explicit user action. The wallet authorizes the decrypt flow, and the UI may hide the revealed value again.

Wallet-Scoped Access

Droptron treats wallet address as the primary access boundary.

  • Workspace pages check that the connected wallet owns or belongs to the cached workspace.
  • Claim pages list only airdrops and vesting schedules assigned to the connected wallet.
  • Switching wallets clears mismatched workspace state and re-checks access.
  • Recipient detail routes redirect back to /claim if the connected wallet is not eligible for that record.

Route Map

/                         product landing page
/app                      product entrance
/app/onboarding           workspace setup
/app/overview             workspace overview
/app/dashboard            operations dashboard
/app/campaigns            distribution ledger
/app/campaigns/new        campaign builder
/app/campaigns/[id]       distribution detail and operation controls
/claim                    recipient claim portal
/claim/airdrop/[id]       single airdrop claim
/claim/vesting/[vestingId] single vesting claim
/app/settings             workspace settings

Quality Gates

Before shipping frontend changes:

cd frontend
npm run check

Before shipping contract changes:

cd hardhat
npm run compile
npm run test