Giveaway Passport Whitepaper

1. Problem and Scope

Traditional giveaway systems are typically centralized and opaque. Participants cannot independently verify entry accounting, winner-selection process, or post-hoc data changes. Giveaway Passport moves critical state transitions on-chain while preserving practical integration paths for provider backend systems.

In scope:

• Unique passport identity per wallet.
• Provider authorization via registry approval.
• Giveaway creation with deterministic identifier and metadata reference.
• Entry issuance/removal by approved providers.
• Rolling giveaways with repeat cadence (every X days, active Y days).
• Entry carry-over across rolling rounds (provider-configurable).
• Passport-owner provider connection controls (disconnect/reconnect).
• Winner declaration according to configured mode.
• Optional winner receipt confirmation flow.

2. Design Principles

• On-chain minimality: canonical state on-chain, rich content off-chain.
• Deterministic interfaces: stable function signatures and machine-readable API errors.
• Operational realism: explicit handling for lag, RPC throttling, and replay recovery.
• Backward continuity: multi-read support across contract migrations.

3. Actors and Trust Boundaries

• Entrant: wallet owner with a passport.
• Provider: approved business wallet managing giveaways and entries.
• Registry owner/admin: governance over provider approvals and platform settings.
• Service operator: runs indexers, APIs, relayers, cron jobs, and admin interfaces.

Chain state is canonical. Indexed database state is convenience state and must be recoverable.

4. System Architecture

1. Chain layer: GiveawayPassport, ProviderRegistry, GiveawayEntries.
2. Index layer: event scanners with checkpoint cursors.
3. Service layer: API routes for provider/admin/user actions and orchestration.
4. UI layer: entrant, provider, admin, analytics, and documentation pages.

5. Network and Layer Choice

The protocol is designed for EVM Layer 2 deployment and is currently operated on Base Sepolia for testing and integration. Production targets Base mainnet when operational readiness and economics are acceptable.

Why Layer 2 (Base):

• Lower median transaction fees than L1 for high-frequency entry operations.
• EVM compatibility for standard tooling (Foundry, ethers, wallet providers, block explorers).
• Fast confirmation characteristics suited to interactive provider dashboards and APIs.
• Practical UX for many small writes (issue/remove entries) without prohibitive user cost.

Environment separation:

• Testnet (Base Sepolia): contract validation, integration testing, staging operations.
• Mainnet (Base): production state, real economic cost, hardened monitoring requirements.

6. Smart Contract Specification

6.1 GiveawayPassport

Transferable ERC-721 identity token contract providing stable participant IDs.

• Multiple passports per wallet are supported.
• Providers/admin can mint for entrant wallets.
• Passports can transfer between wallets for custody/recovery flows.
• Issuer can set per-passport transfer cap at mint time: 0=non-tradable, 1=one transfer, omit for unlimited.
• Passport metadata supports dual mode: optional metadata URI and optional on-chain image URI.
• Passport metadata can be frozen by owner to prevent further updates.

6.2 ProviderRegistry

Governance registry that approves/revokes providers and stores provider metadata URI.

6.3 GiveawayEntries

Canonical entry accounting contract. Primary mapping is (giveawayId, passportId) -> totalEntries . Giveaway records are not NFTs; they are structured contract state with metadata pointers.

• Giveaways support dual metadata mode: optional metadata URI and optional on-chain image URI.
• Each rolling round can also store optional metadata URI and optional on-chain image URI.
• Round outcomes are emitted and indexed so every completed round is independently auditable.

6.4 Temporal Rules

• Start/end are optional (0 is unbounded).
• If both are set, end > start is required.
• Provider-controlled giveaways can be open-ended. A provider may omit end entirely and decide winner timing operationally.
• Auto-draw mode requires a defined end time for non-rolling giveaways.
• Rolling mode uses start as anchor, then repeats every rollingIntervalSeconds with active window rollingActiveSeconds.
• Rolling giveaways can remain open-ended overall by setting start and leaving end unbounded.
• When rolling is enabled, entry totals continue to accumulate across rounds if carry-over is enabled.

6.5 Passport-owner provider controls

Passport holders can disconnect a provider from their passport. While disconnected, that provider cannot issue or remove entries for that passport until reconnected by the passport owner.

7. Canonical Workflows

7.1 Passport Mint

1. Wallet connects on required chain.
2. System checks current ownership.
3. User signs and submits mint transaction if needed.
4. Indexer records mint; chain fallback supports immediate correctness if lagged.

7.2 Provider Lifecycle

1. Provider applies.
2. Admin approves (or auto-approve mode is active).
3. Provider receives API key and starts server-side integration.

7.3 Giveaway Lifecycle

1. Create giveaway with determination and receipt settings.
2. Optionally set giveaway metadata URI/image and round metadata URI/image (pay-on-use writes).
3. Issue/remove entries as business events occur.
4. Entrants can transfer entries between passports during open entry windows.
5. Determine winner per configured mode, either manually at provider-chosen time or by on-chain random draw.
6. After winner resolution, provider can attach a winner/round image by updating the resolved round image URI.
7. Optionally confirm receipt.
8. Prize delivery proof can be recorded on-chain (asset contract, recipient, chain id, proof tx hash, URI).
9. For rolling giveaways, repeat winner resolution on each closed round while preserving accumulated entries.

Off-platform transfers are supported by design. Provider APIs can reconcile ownership with ownerOf(passportId) checks or via GET /api/provider/integrations/passport-status before issuing/removing entries.

8. Winner Determination Modes

• Type 0: No determination.
• Type 1: Provider determination. Provider chooses the winner and chooses when to declare them.
• Type 2: On-chain random draw (manual trigger by provider when ready).
• Type 3: Auto on-chain random draw (cron-triggered after end time, or per closed rolling round).

Auto draw is eligibility-enforced by contract and execution-triggered by automation. If automation is down, draw is delayed rather than invalid.

This makes the model intentionally flexible: providers can run fixed-window campaigns, perpetual open-ended campaigns, or rolling campaigns, and can either choose winners themselves or let the chain choose winners based on the configured mode.

9. Provider and Admin API Model

Provider APIs are server-to-server, authenticated by provider API key (`x-api-key`), and return structured status + error payloads. Provider-scoped passport provisioning/mint helper flows follow the same key model.

• Create giveaway.
• Issue entries.
• Remove entries.
• Declare winner / draw winner.
• Confirm receipt by provider (when enabled).
• Set giveaway/round metadata URI or on-chain image URI.
• Set winner/round image after winner declaration using the resolved round index.
• Record prize delivery proof.

9.1 Passport Ownership Modes

• Direct entrant wallet: mint to entrant wallet directly.
• Managed wallet: mint to provider/platform managed entrant wallet.
• Transfer existing passport: transfer from source wallet to entrant wallet.
• Issuer inventory + claim: issuer mints passports to issuer-owned wallets, then transfers specific passport IDs to entrant wallets after claim verification.
• Provider UX flexibility: providers can onboard users immediately with managed wallets, and later expose UI flows that let users connect their own wallet and transfer passport ownership into self-custody.
• Migration path: this means providers do not need to block participation on wallet setup on day one, but can still offer direct-wallet ownership later for users who want it.

10. Error Semantics and Retry Contracts

• VALIDATION_ERROR: input invalid, no retry until corrected.
• AUTH_ERROR: credentials invalid/scope failure.
• STATE_CONFLICT: on-chain precondition failed.
• INSUFFICIENT_FUNDS: signer balance too low for gas.
• RPC_RATE_LIMIT: 429 throttling, retry with backoff + jitter.
• TX_REVERT: deterministic execution failure.
• TX_TIMEOUT: submission uncertain, reconcile by tx hash.

11. Indexing, Lag, and Recovery

Lag blocks = latestChainBlock - lastIndexedBlock. High lag indicates delayed projections, not loss of canonical chain data.

1. Persist per-contract cursors.
2. Replay in bounded block windows.
3. Upsert idempotently by (txHash, logIndex).
4. Index ERC-721 Transfer events and derive current owner from latest transfer per passport.
5. Apply adaptive retry on throttled RPC calls.

12. Private Profile and Selective Disclosure

Personal fields are encrypted off-chain and unlocked via wallet-signature authentication. Field-level sharing to approved providers is optional and revocable.

13. Security Model

• Registry-gated provider writes.
• Contract precondition enforcement with explicit errors.
• API key hashing and signer isolation.
• Challenge nonce expiry and replay resistance.
• Structured operational audit logging.

14. Gas and Cost Model

Transaction cost varies by network fee market, calldata size, and storage writes. On Base Sepolia, displayed wallet estimates can still fluctuate significantly; on Base mainnet, the same relative ordering applies but with real economic impact.

14.1 Core transaction cost categories

• Passport mint: first-time entrant onboarding transaction; pays for identity token creation state.
• Create giveaway: usually higher cost due to multiple config writes and larger event emission.
• Issue entries: typically lower-cost incremental write.
• Remove entries: can be similar to or higher than issue depending on code path and checks.
• Declare/draw winner: moderate cost, depends on determination mode and state touched.
• Confirm receipt: lower-to-moderate cost depending on payer mode and status transitions.

14.2 Who pays gas

• Entrant-paid: entrant wallet pays passport mint and entrant-side confirmation calls.
• Provider-paid direct: provider wallet signs and pays for giveaway/entry/winner writes.
• Provider-paid relayed: service signer pays at submission time and provider is billed off-chain.
• Configurable receipt mode: giveaway config can require provider-paid receipt confirmation.

14.3 Why some actions cost more

• More storage writes and first-write slots increase gas materially.
• Larger events/calldata increase L2 data costs.
• Complex branching and additional validation checks increase execution gas.
• Fee market spikes can dominate total transaction price even with stable gas usage.

14.4 Cost controls

• Keep on-chain payload minimal and use metadata URIs for heavy content.
• Use optional on-chain image writes only when provenance value justifies higher gas.
• Because metadata/image setters are separate calls, baseline mint/create costs remain unchanged if skipped.
• Use dedicated RPC and monitor throughput limits to reduce retries and delays.
• Alert on low signer balances before write operations fail.
• Implement idempotency keys so provider systems can safely retry without duplicates.

15. Upgrade and Migration Strategy

1. Deploy new contract set.
2. Enable multi-read indexing across legacy and new addresses.
3. Switch write target via environment/config.
4. Validate reconciliation parity.
5. Keep historical readers active.

Provider integrations should remain stable through API abstraction, even when underlying contract addresses change.

16. Operational Runbook

• Monitor lag blocks, RPC error rates, signer balances, and failed tx reasons.
• Run index sync and auto-draw jobs on schedule with backoff-aware workers.
• Expose admin controls for manual sync/draw interventions.

17. Limitations and Future Work

• Randomness guarantees are weaker without VRF.
• Metadata URI durability depends on external storage strategy.
• Managed entrant provisioning needs careful custody/compliance design.

18. Glossary

• Passport: on-chain entrant identity token.
• Provider: approved wallet authorized to manage giveaways.
• Giveaway ID: bytes32 giveaway namespace key.
• Lag Blocks: chain head minus last indexed block.
• Relayer: service component broadcasting API-originated transactions.