Brief Whitepaper

This white paper describes the architecture and operating principles of the VoteNFT smart contract, the core engine of Punkpoll, a decentralized voting protocol built on the Avalanche blockchain. The VoteNFT contract integrates NFT issuance, voting logic processing, and reward token management into a single, optimized monolithic structure to maximize gas efficiency and simplify deployment.

Specifically, this document details key mechanisms including the immutability of rules via immutable variables, gas abstraction using ERC2771Context-based Trusted Forwarders, and the atomic handling of 'NFT retrieval' and 'reward distribution' within a single function call. Additionally, by recording the ipfsHash on-chain to guarantee off-chain data integrity, this integrated architecture demonstrates how it enables trust-minimized, tamper-proof, and cost-efficient decentralized data collection.

Introduction

Surveys and voting, fundamental tools for data collection and decision-making in modern society, still heavily rely on centralized platforms, inherently facing issues such as data monopolization, lack of transparency, and potential manipulation. While blockchain-based decentralized voting systems have been proposed as alternatives, they have encountered technical dilemmas balancing high on-chain costs against trust concerns with off-chain methods.

Punkpoll’s VoteNFT smart contract provides a practical and sophisticated solution to this dilemma, addressing the question: "How can we adhere to the decentralized principle of trust, while minimizing the cost and experiential barriers encountered by actual users?" The answer lies in avoiding complex multi-contract architectures and instead integrating all essential functionalities into one highly optimized contract.

The objective of this white paper is to describe Punkpoll's technical originality based on the actual implementation of VoteNFT.

Chapter 1 explains the integrated contract architecture, which encompasses NFT issuance, reward management, and voting logic.
Chapter 2 details the atomic execution mechanism enabled by Trusted Forwarders and the method for ensuring data integrity through ipfsHash recording.
Lastly, this paper comprehensively evaluates the technical impacts and security model of the architecture and explores its future potential.

Chapter 1: VoteNFT Architecture – An Integrated Smart Contract Maximizing Efficiency

1.1. Design Philosophy: Immutability, Simplicity, and Gas Efficiency

The VoteNFT contract employs a monolithic architecture, designed such that a single contract executes all essential functions rather than relying on interactions between multiple contracts. This architecture is based on a clear and deliberate design philosophy as follows:

Immutability by Design:
Most core rules, including the survey period (START_TIME, END_TIME), voter identity (VOTER), reward tokens (REWARD_TOKEN), and reward amount (REWARD_AMOUNT), are declared as immutable variables within the contract’s constructor. Once deployed, these rules cannot be altered by anyone, including the contract owner. This ensures that trust in the system is rooted firmly in immutable code rather than in any operating entity, providing a robust security guarantee.

Structural Simplicity:
By integrating NFT issuance (ERC721), fund management (ERC20), access control (Ownable), and gas fee delegation (ERC2771Context) functionalities into a single contract, the system simplifies deployment and management. This significantly reduces potential errors and security risks inherent in complex inter-contract interactions.

Gas Efficiency:
Immutable variables consume considerably less gas than traditional storage variables. Additionally, processing all logic within a single contract eliminates extra gas costs typically associated with external calls between contracts. This serves as a critical optimization strategy, substantially reducing overall operational costs in surveys anticipating high participation rates.

1.2. Integrated Roles: NFT, Treasury, and Logic Engine

The VoteNFT contract concurrently performs three core roles:

NFT Issuance and Management (ERC721URIStorage):
The contract itself represents an NFT collection adhering to the ERC-721 standard. Through functions such as mintNFT and batchMintNFT, the contract owner can issue unique voting-right NFTs to eligible participants.

Treasury/Vault:
The contract acts as a vault, directly holding and managing ERC-20 tokens designated as REWARD_TOKEN. It accepts deposits via the depositRewardTokens function and directly rewards participants using the internal _rewardUser function. Additionally, completed voting NFTs are reclaimed and stored within the contract’s own address (address(this)).

Voting Logic Engine:
Through functions such as the registerParticipation... series, the contract verifies voting participation conditions, updates state variables (hasParticipated, participantCount), and sequentially executes NFT retrieval and reward distribution as core logic. This integrated design moves beyond a mere proof-of-concept, addressing practical concerns regarding efficiency and cost in real-world operation.

1.3. Transaction Lifecycle

The actual operational flow of the VoteNFT contract is as follows:

Stage 1: Preparation (Survey Organizer)

Deployment and Rule Finalization:
The organizer deploys the VoteNFT contract, permanently setting all survey rules—such as survey content, period, reward amount, target or maximum number of participants—as immutable variables within the constructor.
Reward Deposit:
The organizer invokes the depositRewardTokens function to deposit the total reward tokens into the contract, intended for distribution to participants.
Voting Rights Issuance:
The organizer issues voting-right NFTs to eligible participants' wallets by calling mintNFT or batchMintNFT. Participants thus possess verifiable on-chain voting rights.

Stage 2: Participation (User + Trusted Forwarder)

Off-Chain Response and Signature:
Users respond to surveys via the Punkpoll interface (web/app). The response data is uploaded to off-chain storage like IPFS, generating a unique data fingerprint known as an ipfsHash. Users cryptographically sign the ipfsHash along with their intent to participate.
Submission via Forwarder:
Signed user requests are sent to a trusted forwarder (relayer server). The forwarder pays the gas fee (AVAX) on behalf of the user and calls the registerParticipationByReturningNFTForUser function of the VoteNFT contract, passing the participant’s address, tokenId (voting-right NFT), and the ipfsHash as parameters.

Stage 3: Atomic Execution (Smart Contract)

The following processes occur atomically within a single transaction when the registerParticipationByReturningNFTForUser function is called:

Eligibility Verification:
The contract strictly verifies the survey period, participant eligibility, duplication of participation, and the legitimacy of the function caller as a trusted forwarder (isTrustedForwarder).
NFT Retrieval:
Through the internal _transfer function, the participant’s voting-right NFT is forcefully transferred back to the contract itself (address(this)), signifying an on-chain record of completed voting.
Reward Distribution:
The contract immediately transfers the stored reward tokens to the participant’s wallet via the internal _rewardUser function, which also serves as a receipt.
Recording:
A Participated event is emitted, permanently recording the participant’s address, the returned NFT ID, and the response data hash (ipfsHash) within the blockchain log.

This process clearly establishes "vote submission" and "reward receipt" as an indivisible, single transactional unit. By transferring NFT ownership to the voting smart contract, users instantly receive guaranteed rewards (as receipts), completely eliminating counterparty risks.

Chapter 2: Core Mechanisms and Their Effects

2.1. Atomic Execution via Trusted Forwarder

Punkpoll implements a secure and controlled atomic execution using ERC2771Context and the Trusted Forwarder pattern. ERC2771Context is a standard for meta-transactions, allowing contracts to differentiate between the end-user (_msgSender()) and the intermediary forwarding the transaction (msg.sender). VoteNFT leverages this mechanism by restricting access to critical functions such as registerParticipation... to only owner-approved forwarder addresses using the requirement require(isTrustedForwarder(msg.sender), "Caller not authorized").

Effects of this structure include:

Guaranteed Atomicity: The logic for 'NFT retrieval' and 'reward distribution' is executed sequentially within a single function, ensuring stronger atomicity, independent of external NFT receipt events.
Enhanced Security: Prevents unintended function executions triggered by unauthorized NFT transfers. Only trusted pathways can initiate voting logic, significantly reducing the system's attack surface.
Gas Abstraction (Improved UX): Users can participate simply by off-chain signatures without needing AVAX tokens or complex gas payment procedures. All complex on-chain processes are managed by the forwarder, offering user experiences comparable to Web2 services, facilitating smooth system operations for both organizers and participants.

2.2. ipfsHash: On-chain Proof of Off-chain Data Integrity

The VoteNFT contract does not directly record users' detailed voting responses (e.g., "Yes," "Option A") on-chain to intentionally protect user privacy and minimize gas fees. Instead, the registerParticipation function accepts an ipfsHash as an argument.

Operation: Actual user response data is stored on decentralized storage like IPFS, generating a unique Content Identifier (CID), the ipfsHash. This hash is included in on-chain transactions and recorded in the Participated event log, enabling proof of data integrity.

Technical Benefits:

Data Integrity: ipfsHash acts as a 'fingerprint' for data. Any alteration to off-chain data results in a completely different hash, allowing verification that data remains unchanged since submission.
Cost Efficiency: Storing only fixed-length hashes on-chain instead of extensive response data dramatically reduces gas costs.
Privacy: Voting choices are protected by not publicly recording responses on-chain, although IPFS data access control is a separate concern.

2.3. Technical Advantages

The architecture of the VoteNFT contract provides several significant technical advantages:

Trust-Minimized Operations: Participants receive guaranteed execution of publicly defined immutable rules and automated logic without relying on trust in organizers.
Complete Tamper-Proofing: Blockchain inherently prevents alteration of on-chain records (participation status, ipfsHash), ensuring authenticity of off-chain data via IPFS-generated hashes.
Guaranteed Incentives: Participation and reward distribution are processed atomically, immediately and definitively rewarding participants for their responses.
Excellent User Experience (UX): Gas abstraction enables user-friendly participation methods akin to Web2, mitigating Web3 complexities.

Chapter 3: Conclusion – Punkpoll’s Practical Decentralization Vision and Future Strategies

Punkpoll's VoteNFT smart contract embodies a decentralized voting system that bridges ideals with practical realities, born from extensive contemplation and research. Rather than blindly pursuing theoretical complete decentralization, Punkpoll precisely identifies and efficiently addresses practical issues faced by real users and organizers.

The success of any voting system ultimately stems from user convenience and practical utility. Thus, Punkpoll carefully implements engineering strategies to achieve realistic goals—gas efficiency and significantly improved UX—while strictly preserving blockchain's core values of transparency, automation, and data immutability.

VoteNFT integrates optimized techniques such as a monolithic structure, immutable rules, atomic execution through trusted forwarders, and on-chain/off-chain integration via ipfsHash, generating powerful synergies. The result is more than mere voting; it represents a scalable model with broader ecosystem applicability, demonstrating clear advancement directions for decentralized protocols.

Nonetheless, Punkpoll acknowledges practical challenges such as centralized management authority, forwarder service reliability, and long-term IPFS data availability. Concrete solutions, including multi-signature wallets, Timelock-based governance models, independent decentralized forwarder networks, and active IPFS pinning strategies, are already in place and actively pursued.

Ultimately, Punkpoll advocates a decentralization model that is practically meaningful and operational in the real world—blockchain technology as a powerful, accessible tool easily leveraged by users. The VoteNFT contract clearly and realistically represents this practical decentralization vision. Punkpoll remains committed to continuously refining this model, building a trustworthy and accessible decentralized voting ecosystem for global participation.