Skip to content

Final report for GSoC 2025 for Agora Blockchain project by Hamad Hussain #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Final report for GSoC 2025 for Agora Blockchain project by Hamad Hussain #5

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 166 additions & 0 deletions Hamad_Hussain.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
# Google Summer of Code 2025 Final Project Report

## Student Information

- **Name:** Hamad Hussain
- **GitHub:** [therealhamad](https://github.com/therealhamad)
- **Social Profiles:** [LinkedIn](https://www.linkedin.com/in/therealhamad/)
- **Organization:** [Australian Open Source Software Innovation and Education (AOSSIE)](https://www.aossie.org/)
- **Project:** [Agora-Blockchain — Enhancing Agora Blockchain: Privacy, Cross-Chain Voting, and Seamless User Onboarding](https://github.com/AOSSIE-Org/Agora-Blockchain)

## Abstract

I implemented three major capabilities in the Agora-Blockchain stack during the GSoC 2025 period:
1) Web2/Social authentication using Web3Auth (Google and other providers),
2) Account Abstraction (ERC‑4337) with optional gasless voting via Pimlico bundler/paymaster,
3) Private elections with multi‑identifier whitelisting and fine‑grained access control.

These features make decentralized voting significantly more accessible while preserving strong privacy and authorization guarantees. Users can log in with familiar social identities, vote without managing gas, and election creators can restrict participation to specific individuals or wallets.

## Technologies Used

- **Frontend**: Next.js (App Router), Tailwind CSS, React, Wagmi, Viem
- **Blockchain**: Solidity, Hardhat, OpenZeppelin, Ethers/Viem
- **AA & Gasless**: ERC‑4337 Smart Accounts, Pimlico Bundler & Paymaster
- **Authentication**: Web3Auth (Torus), Google & social identity providers
- **Tooling**: TypeScript, Jest/Hardhat tests, Docker

## GitHub Repository

[Agora-Blockchain ](https://github.com/therealhamad/Agora-Blockchain)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix MD039: remove trailing space inside link text.

There’s an extra space before the closing bracket in the GitHub repo link, which violates markdownlint MD039 and can affect rendering in some parsers.

Apply this diff:

-[Agora-Blockchain ](https://github.com/therealhamad/Agora-Blockchain)
+[Agora-Blockchain](https://github.com/therealhamad/Agora-Blockchain)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
[Agora-Blockchain ](https://github.com/therealhamad/Agora-Blockchain)
[Agora-Blockchain](https://github.com/therealhamad/Agora-Blockchain)
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

30-30: Spaces inside link text

(MD039, no-space-in-links)

🤖 Prompt for AI Agents 
In Hamad_Hussain.md around line 30, the markdown link text contains a trailing
space ("[Agora-Blockchain ]") which violates MD039; remove the extra space so
the link text is "[Agora-Blockchain]" and keep the URL unchanged to fix the lint
error and ensure proper rendering.


## Demos

1. [Web2/Social Auth Demo](https://youtu.be/GbkrCnFYqio)
2. [Account Abstraction Demo](https://youtu.be/aAIFx-lQacM)
3. [Private Election Demo](https://youtu.be/lzMFWqXIQWw)

### Key Flows
1. Social Login + Smart Account initialization
2. Private Election creation with whitelist
3. Gasless (sponsored) vote cast via Smart Account
4. Direct-call fallback vote (when AA is unavailable)

### Test Deployments

- Contracts: Sepolia Testnet [0x1De2a1ABe13Ed3e3067b67Aba8B60306FAc240fb](https://sepolia.etherscan.io/address/0x1De2a1ABe13Ed3e3067b67Aba8B60306FAc240fb) (addresses tracked in `client/app/constants.ts` and `blockchain/ignition/deployments`)
- Frontend: [Website](https://agora-blockchain.vercel.app/) Local and containerized runs; public preview as available during evaluations

## Project Description

The work targeted three pillars. Below is the high-level description and concrete artifacts.

### 1) Web2/Social Login with Web3Auth

Implemented a robust Web3Auth integration to derive a reliable user identifier for authorization and UX:
- Extracts social identity (e.g., Google email) from Web3Auth `userInfo`, with resilient detection (handles cases where `typeOfLogin` is undefined by using `groupedAuthConnectionId` / `verifier`).
- Provides wallet fallbacks when social data is unavailable.
- Exposes a simple helper `getCurrentUserIdentifier` used throughout the app.

Primary files:
- `client/app/helpers/userIdentification.ts`
- `client/app/context/Web3AuthContext.tsx`

Comment on lines +55 to +63
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Avoid logging PII from Web3Auth in production.

The report mentions logging userInfo and detailed UI logs. Emails/user identifiers are PII; ensure production builds redact them and that logs are sampled/retained minimally with access controls.

Add an explicit note: “Production logs redact emails/identifiers; only hashed/non‑PII telemetry is retained with X‑day TTL.”

Also applies to: 101-105

🤖 Prompt for AI Agents 
In Hamad_Hussain.md around lines 55 to 63, the PR currently logs full Web3Auth
userInfo (PII) and lacks a production redaction note; update the code and docs
to avoid emitting emails/identifiers in production by replacing raw userInfo
logs with redacted/hased identifiers (e.g., hash email or log only
provider+hashedId) and conditional logging that disables PII in
NODE_ENV=production, add sampling/minimal retention controls and configure a TTL
for log storage, and add the explicit note line “Production logs redact
emails/identifiers; only hashed/non‑PII telemetry is retained with X‑day TTL.”
(also apply same changes/note to lines ~101-105 referenced in the comment).

Outcome: Consistent, debuggable identity information available to the UI and the voting flow.

### 2) Account Abstraction + Gasless Voting

Integrated ERC‑4337 smart accounts with Pimlico bundler/paymaster to enable sponsored voting:
- Uses smart account for `userVote` when sponsorship is enabled.
- Provides detailed logging of the entire user operation lifecycle for diagnosis.
- Falls back to a direct ethers signer call if AA signing is unavailable (ensuring UX continuity).

Primary files:
- `client/app/helpers/smartAccountV2.ts` (UserOp prepare/send, paymaster flow)
- `client/app/components/Modal/Vote.tsx` (encoding via Viem, AA vs direct-call logic)

Outcome: Users can vote without manually funding gas, with a reliable fallback path.

### 3) Private Elections with Multi‑Identifier Whitelisting

Designed and implemented private elections at the contract and frontend layers.

Smart Contracts:
- `Election.sol`
- `ElectionInfo { name, description, startTime, endTime, isPrivate }`
- `WhitelistEntry { identifier, identifierType, isActive }` where identifierType: 0=email, 1=twitter, 2=farcaster, 3=github, 4=wallet
- O(1) whitelist lookup via `keccak256(abi.encode(identifier, identifierType))`
- Access checks in `userVote` using `isWhitelisted(msg.sender, userIdentifier, identifierType)`
- `addToWhitelist` permissioned by `onlyOwnerOrFactory`

Comment on lines +84 to +90
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Whitelist data model: hash-only storage + normalization.

Storing identifier in WhitelistEntry risks on‑chain PII leakage. Prefer storing only keccak256(abi.encode(canonical(identifier), identifierType)) and omit raw identifiers on‑chain. Also define canonicalization (e.g., lower‑case emails, trimmed, Unicode NFC).

Add a sentence clarifying canonicalization and whether only hashes are persisted on‑chain.

🤖 Prompt for AI Agents 
In Hamad_Hussain.md around lines 84 to 90, the whitelist model currently stores
raw identifiers which risks on‑chain PII; change the design to persist only
keccak256(abi.encodePacked(canonical(identifier), identifierType)) on‑chain
(remove raw identifier from WhitelistEntry), and explicitly define the
canonicalization rules (e.g., trim whitespace, convert emails/usernames to
lowercase, apply Unicode NFC normalization, and any service‑specific rules) so
all input is normalized before hashing; ensure access checks and
addToWhitelist/update/remove functions accept the raw identifier but perform
canonicalization off‑chain or in a helper, compute the hash, and only
store/compare the hash on‑chain, and update events/logs to avoid emitting raw
identifiers.

- `ElectionFactory.sol`
- `createPrivateElection` enforces `isPrivate=true`, validates whitelist, optionally accepts sponsorship value
- Maintains public/private registries and exposes getters

Frontend:
- Creation (`client/app/create/page.tsx`)
- Validates inputs and enhances whitelist by auto-adding creator’s relevant wallets (Web3Auth, wagmi, smart account) as type‑4 entries to satisfy `msg.sender` checks at vote time
- Uses extended ABIs to match updated contract signatures
- Provides detailed logs for debugging

- Voting (`client/app/components/Modal/Vote.tsx`)
- Extracts identifier via Web3Auth, sends `userVote(votes, userIdentifier, identifierType)`
- Correctly handles `identifierType` using `??` (preserves 0 for email)
- Selects AA or direct call path; surfaces error context in UI logs

Outcome: Only whitelisted users (by email/social or wallet) can access and vote in private elections; public elections remain open.

## Relevant Pull Requests / Major Changes

1. Smart Contract Enhancements
- Added sponsorship support (`isSponsored`) in `Election.sol`
- Added private election support (`isPrivate`), whitelist structs, and access checks in `Election.sol`
- Implemented `createPrivateElection`, sponsorship validation, and getters in `ElectionFactory.sol`

2. Frontend Whitelist & ABI Integration
- Extended ABIs to include `createPrivateElection` and updated `userVote`
- Auto-whitelist wallet identities during creation; comprehensive logging across flows

3. Account Abstraction & Fallback Path
- Implemented sponsored voting via Pimlico; added resilient fallback to direct ethers call

4. Developer Experience & Debuggability
- Rich console diagnostics; decoding scripts; improved error messages; type fixes

Here are the major PRs I've made:

PR #168: [feat: implemented web2 login method](https://github.com/AOSSIE-Org/Agora-Blockchain/pull/168)

PR #169: [feat: implemented account abstraction for sponsoring gasless voting](https://github.com/AOSSIE-Org/Agora-Blockchain/pull/169)

PR #171: [feat: implemented private elections option to enable voting for whitelisted users only](https://github.com/AOSSIE-Org/Agora-Blockchain/pull/171)

## Challenges and Solutions

1. ABI and Encoding Incompatibilities
- Issue: Mixed ethers v5/v6 patterns caused encoding/constructor errors and duplicate ABI signatures.
- Solution: Unified on Viem for encoding; created Extended ABIs; filtered legacy `userVote` signature.

2. Web3Auth Identifier Edge Cases
- Issue: `typeOfLogin` sometimes undefined.
- Solution: Added alternative detection via `groupedAuthConnectionId` and `verifier`; logged `userInfo` for clarity.

3. Whitelist vs msg.sender Mismatch
- Issue: Contract checks both identifier and `msg.sender` for private votes; some wallets weren’t in the list.
- Solution: Auto-append Web3Auth/wagmi/smart-account addresses (type‑4) to whitelist during creation.

4. AA Signing / Provider Issues
- Issue: "Unable to find matching address" from Torus in some environments.
- Solution: Provide robust direct-call fallback so users can still vote; kept logs to isolate infra issues from app logic.

## Future Plans

1. Improve the production build
2. Conduct smart contract audits
3. Further optimize smart contracts
4. Improve AA provider compatibility and recovery flows
5. Management UI for whitelist (bulk uploads, status toggles, audit trail)
6. Role-based admin actions (delegation, moderators)
7. CI scripts to auto-sync ABIs/addresses and smoke-test flows
8. Add support for multiple blockchains

## Acknowledgements

I’m grateful to my mentors Roshan Raj, Aditya Bhattad, Bruno Woltzenlogel Paleo and the AOSSIE community for guidance, code reviews, and rapid feedback loops throughout the summer.