AsyncSwap - Uniswap V4 Hook with Chainlink VRF

A Uniswap V4 hook that uses Chainlink VRF for asynchronous randomized swaps

Overview

AsyncSwap is a Uniswap V4 hook with the following pillars:

• VRF-powered mechanics – Chainlink VRF drives every swap outcome so randomness is verifiable.
• Two execution modes – starts on a Pump.fun-style bonding curve, then auto-migrates to standard Uniswap V4 liquidity once the ETH raised crosses the graduation threshold.
• Pluggable game logic – the current Smuggler module rolls buys between Clean Run (40%), Ambush (30% burns 15-50%), and Drop Spotted (30% bonus mint) while sells roll between DEI (40% cancel + cooldown), Ambush (30% pre-swap burn), and Drop Spotted (30% pre-swap mint); any other IGameMechanics contract can be dropped in.
• Referral system – swaps feed a shared referral contract so creators can reward promoters across every hook deployment.

Core Contracts

• BamboozleHook.sol – the async swap hook that runs the bonding curve, VRF mechanics, and Uniswap V4 migration logic end to end.
• BamboozleHookFactory.sol – thin CREATE2 factory the launchpad uses to deploy hooks with pre-mined salts.
• BamboozleLaunchpad.sol – orchestrates token deployments, wires VRF config, seeds the pool, and hands ownership to the hook in one transaction.
• BamboozleToken.sol – ERC20 with mint/burn/cooldown roles so mechanics can add bonus supply, burn ambush losses, or freeze sellers.
• ReferralManager.sol – shared referral + fee splitter that tracks referrers across hooks and pays them from swap fees.

Deployed on: Base Sepolia & Base Mainnet

Requirements

This template is designed to work with Foundry (stable). If you are using Foundry Nightly, you may encounter compatibility issues. You can update your Foundry installation to the latest stable version by running:

foundryup

To set up the project, run the following commands in your terminal to install dependencies and run the tests:

forge install
forge test

Local Development

Deployment scripts are available in script/ directory:

• 00_DeployHook.s.sol - Deploy AsyncSwap hook with Chainlink VRF configuration
• 01_CreatePoolAndAddLiquidity.s.sol - Create pool and add initial liquidity
• 02_WhitelistPool.s.sol - Whitelist the pool for async swaps
• 03_Swap.s.sol - Execute a swap that triggers VRF request
• FulfillSwap.s.sol - Manually fulfill pending swap (emergency use if automatic fulfillment fails)
• 04_MultiSwap.s.sol - Execute multiple swaps

Scripts support both local anvil environment and production networks (Base Sepolia, Base Mainnet).

Executing locally with using Anvil:

1. Start Anvil (or fork a specific chain using anvil):

anvil

or

anvil --fork-url <YOUR_RPC_URL>

2. Execute scripts:

forge script script/00_DeployHook.s.sol \
    --rpc-url http://localhost:8545 \
    --private-key 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d \
    --broadcast

Using RPC URLs (actual transactions):

:::info It is best to not store your private key even in .env or enter it directly in the command line. Instead use the --account flag to select your private key from your keystore. :::

Follow these steps if you have not stored your private key in the keystore:

Details

1. Add your private key to the keystore:

cast wallet import <SET_A_NAME_FOR_KEY> --interactive

2. You will prompted to enter your private key and set a password, fill and press enter:

Enter private key: <YOUR_PRIVATE_KEY>
Enter keystore password: <SET_NEW_PASSWORD>

You should see this:

`<YOUR_WALLET_PRIVATE_KEY_NAME>` keystore was saved successfully. Address: <YOUR_WALLET_ADDRESS>

::: warning Use history -c to clear your command history. :::

1. Execute scripts:

forge script script/00_DeployHook.s.sol \
    --rpc-url <YOUR_RPC_URL> \
    --account <YOUR_WALLET_PRIVATE_KEY_NAME> \
    --sender <YOUR_WALLET_ADDRESS> \
    --broadcast

You will prompted to enter your wallet password, fill and press enter:

Enter keystore password: <YOUR_PASSWORD>

Configuration

Before deployment, update script/base/BaseScript.sol:

1. Chainlink VRF Configuration:

   • subscriptionId - Your Chainlink VRF subscription ID
   • keyHash - Gas lane key hash for your network
   • callbackGasLimit - Gas limit for VRF callback (default: 500,000)

2. Pool Configuration:

   • token0 and token1 - Token addresses for your pool
   • poolFee - Pool fee tier (e.g., 3000 for 0.3%)
   • tickSpacing - Tick spacing for the pool

3. Liquidity Settings:

   • Update amounts in 01_CreatePoolAndAddLiquidity.s.sol

Why 0 Confirmations?

AsyncSwap uses REQUEST_CONFIRMATIONS = 0 on Base for fastest VRF response (~4 seconds):

• Only allowed on AVAX, Base, OP, and Soneium (centralized sequencer chains)
• Chainlink reads from L2 blocks, not flashblocks
• VRF generation (2-4s) is slower than block finalization (~2s)
• Base has 0 documented L2 block reorgs since launch (2+ years)
• Trade-off: <0.01% theoretical risk for 2-4 second UX improvement

Troubleshooting

Details

Permission Denied

When installing dependencies with forge install, Github may throw a Permission Denied error

Typically caused by missing Github SSH keys, and can be resolved by following the steps here

Or adding the keys to your ssh-agent, if you have already uploaded SSH keys

Anvil fork test failures

Some versions of Foundry may limit contract code size to ~25kb, which could prevent local tests to fail. You can resolve this by setting the code-size-limit flag

anvil --code-size-limit 40000

Hook deployment failures

Hook deployment failures are caused by incorrect flags or incorrect salt mining

1. Verify the flags are in agreement:
   • getHookCalls() returns the correct flags
   • flags provided to HookMiner.find(...)
2. Verify salt mining is correct:
   • In forge test: the deployer for: new Hook{salt: salt}(...) and HookMiner.find(deployer, ...) are the same. This will be address(this). If using vm.prank, the deployer will be the pranking address
   • In forge script: the deployer must be the CREATE2 Proxy: 0x4e59b44847b379578588920cA78FbF26c0B4956C
     • If anvil does not have the CREATE2 deployer, your foundry may be out of date. You can update it with foundryup

Testing

The project includes comprehensive stress tests to validate the bonding curve and game mechanics:

Run All Tests

forge test

Run Specific Stress Tests

1000 Cycles Stress Test (detailed output):

TIMESTAMP=$(date +%s) forge test --match-test "test_3_StressTest_1000Cycles" -vvv

Stop at Migration Test (runs until migration or error):

TIMESTAMP=$(date +%s) forge test --match-test test_4_StressTest_StopAtMigration -vv

Migration With Pending Swap (ensures pending swaps are handled safely before migration):

TIMESTAMP=$(date +%s) forge test --match-test test_Migration_WithPendingSwap -vv

Meta-Analysis (500 runs)

Run the automated meta-analysis script to execute 500 independent test runs and aggregate statistics:

./scripts/meta_analysis.sh

This will provide:

• Migration vs Error distribution
• Average cycles per outcome
• Mechanic distribution (mint/burn percentages)
• Net token effects (minted vs burned)
• Net ETH flow analysis

The meta-analysis runs the test_4_StressTest_StopAtMigration test 500 times with different VRF seeds to validate that game mechanics are balanced and fair across many scenarios.

Additional Resources

Uniswap V4:

• Uniswap v4 docs
• v4-periphery
• v4-core
• v4-by-example

Chainlink VRF:

• Chainlink VRF Documentation
• VRF Best Practices
• Base VRF Configuration

Base:

• Base Documentation
• Base Stats (Flashblocks)