NudgeVault Smart Contract

Overview

NudgeVault is a privacy-preserving smart contract for gifting ERC20 tokens on Base. It allows users to send tokens with encrypted messages to recipients identified by privacy-protecting hashes rather than public addresses.

Contract Details

• Contract Address: 0x69e82Efc1C38379c331b48A0C24597086e806ee8
• Network: Base (Chain ID: 8453)
• Compiler: Solidity ^0.8.20
• License: MIT
• Verified Source: View on Basescan

Core Features

Privacy-First Design

Recipient Protection

• Recipients identified by keccak256 hash, not public addresses
• Hash includes FID + wallet address + unique salt
• Impossible to correlate on-chain activity with specific users
• No plaintext recipient data stored on-chain

Message Encryption

• Messages stored as hashes on-chain
• Full message encrypted off-chain before storage
• Only recipient can decrypt using their private salt

Example Privacy Flow:

Recipient Hash = keccak256(
  keccak256(FID + Wallet Address) + Salt
)

Gift Operations

Queue Gift (queueGift)

• Send ERC20 tokens with encrypted message
• Tokens locked in contract until claimed
• Supports any ERC20 token
• Message hash stored for verification

Queue Batch Gift (queueGiftBatch)

• Send to multiple recipients in one transaction
• 30-50% gas savings vs individual gifts
• Same privacy guarantees

Claim Gift (claimGift)

• Recipient proves identity with FID + address + salt
• Contract verifies hash matches
• Tokens transferred directly to recipient
• Double-claim protection via dual tracking

Revoke Gift (revokeGift)

• Gifter can revoke unclaimed gifts
• Returns tokens to original sender
• Cannot revoke after claim

Security Features

Double-Spend Protection

• Dual tracking: claimed flag + claimedGifts mapping
• Nonce-based replay protection
• CEI (Checks-Effects-Interactions) pattern throughout

Rate Limiting

• Minimum 1 block between gifts per sender
• Maximum 100 pending gifts per recipient
• Prevents spam and DoS attacks

Salt Entropy Requirements

• Minimum salt entropy: 2^128
• Prevents brute force attacks on recipient hashes
• Ensures cryptographic security

Emergency Controls

• One-way pause mechanism (can pause, never unpause)
• Emergency pauser role (recommend multisig)
• Blacklist functionality for bad actors
• No admin functions beyond emergency pause

OpenZeppelin Dependencies

• SafeERC20 for secure token transfers
• ReentrancyGuard for reentrancy protection
• Pausable for emergency stops
• Battle-tested, audited libraries

Gas Optimizations

• Tight struct packing: uint96 for amounts, uint32 for timestamps
• Efficient storage layout
• Batch operations for multi-recipient gifts
• Minimal storage reads/writes

Architecture

Storage Structure

struct Gift {
    address gifter;        // Who sent the gift
    address token;         // ERC20 token address
    bytes32 messageHash;   // Hash of encrypted message
    uint96 amount;         // Token amount (packed)
    uint32 timestamp;      // Creation time (packed)
    bool claimed;          // Claim status
}

mapping(bytes32 => mapping(uint256 => Gift)) public gifts;
mapping(bytes32 => uint256) public giftCount;

Key Functions

Function	Purpose	Gas Cost
queueGift	Send single gift	~150k gas
queueGiftBatch	Send batch gifts	~100k + 50k per recipient
claimGift	Claim tokens	~80k gas
revokeGift	Cancel unclaimed gift	~60k gas
checkPendingGifts	View pending gifts	View only (free)

Security Considerations

Audited Patterns

• OpenZeppelin contracts (industry standard)
• CEI pattern (Checks-Effects-Interactions)
• ReentrancyGuard on all state-changing functions
• SafeERC20 for token transfers

Known Limitations

• Application Dependency: Salt management is handled by the Nudge application. Users depend on the app's database for gift claiming.
• Token Approvals: Gifters must approve contract before sending
• Gas Costs: Claiming requires gas fees (paid by recipient)
• Emergency Pause: Once paused, contract cannot be unpaused (by design)

Best Practices for Users

For Gifters:

• Approve exact amount (don't over-approve)
• Verify recipient username before sending
• Use batch operations for multiple recipients

For Recipients:

• Claim gifts promptly (gifter can revoke)
• Verify gift details before claiming
• Ensure you have ETH for gas fees

Nudge Application Architecture

The Nudge Mini App manages salt generation and storage to provide a seamless user experience:

Salt Management (Server-Side)

• Salts are auto-generated when users first interact with the app
• Stored encrypted in Supabase database with AES-256-GCM
• Associated with user's Farcaster FID
• Never exposed to end users directly

Database Security (Supabase)

• Row Level Security (RLS) policies prevent public access to salt table
• Salts only accessible via authenticated API routes with verified FID
• Service role key required for salt operations (stored in secure env vars)
• Database audit logs track all salt access
• Encrypted at rest and in transit

User Experience

• Users don't manage salts manually
• Claiming works automatically when logged in
• Salt is retrieved server-side during claim flow
• No additional steps or backups required

Security Layers

1. Encryption: Salts encrypted with MESSAGE_ENCRYPTION_KEY before storage
2. RLS Policies: Database-level access control prevents unauthorized reads
3. API Authentication: All salt access requires valid Farcaster JWT
4. Service Key Protection: Only server-side routes can decrypt salts

Trade-offs

• ✅ Pro: Seamless UX - users don't manage cryptographic keys
• ✅ Pro: Lower barrier to entry for non-technical users
• ✅ Pro: Multiple security layers (encryption + RLS + auth)
• ⚠️ Con: Users trust Nudge to manage salts securely
• ⚠️ Con: Database unavailability prevents claiming (though gifts remain safe on-chain)

This architecture prioritizes user experience while maintaining strong security through defense-in-depth: encryption, access control, and authentication.

Testing & Verification

Verified on Basescan

The contract source code is verified and publicly viewable on Basescan. You can:

• Read the contract source code
• Verify bytecode matches source
• View all transactions and events
• Check security features

Local Testing

# Clone the repository
git clone https://github.com/jumpboxtech/nudge.git
cd nudge

# Install dependencies
npm install

# Run tests (coming soon)
npm test

Integration Guide

For Developers

1. Queue a Gift

import { parseUnits } from 'viem';

// Calculate recipient hash (server-side with salt)
const recipientHash = keccak256(
  encodePacked(
    ['bytes32', 'bytes32'],
    [
      keccak256(encodePacked(['uint256', 'address'], [fid, wallet])),
      salt
    ]
  )
);

// Approve token
await token.write.approve([VAULT_ADDRESS, amount]);

// Queue gift
await vault.write.queueGift([
  recipientHash,
  tokenAddress,
  parseUnits(amount, decimals),
  messageHash
]);

2. Claim a Gift

await vault.write.claimGift([
  giftId,
  fid,
  recipientAddress,
  salt
]);

Smart Contract ABI

The full ABI is available in /app/lib/contract.ts or can be viewed on Basescan.

Key events:

• GiftQueued - Emitted when gift is created
• GiftClaimed - Emitted when gift is claimed
• GiftRevoked - Emitted when gift is cancelled

Roadmap

Future Enhancements

• Multi-token batch gifts (different tokens in one tx)
• Gift expiration dates
• Gift conditions (claim after X date)
• NFT support
• Governance token integration

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Follow security best practices
4. Add tests for new features
5. Submit a pull request

Security Disclosure: If you discover a security vulnerability, please email nudge@jumpbox.tech (do NOT create a public issue).

License

MIT License - see LICENSE.md

Resources

• Contract: View on Basescan

Disclaimer

This software is provided "as is" without warranty of any kind. Users interact with the smart contract at their own risk. Always verify contract addresses and test with small amounts first.