This guide explains how to create mock versions of mainnet contracts that work seamlessly across different networks (emulator, testnet, mainnet) using the same scripts and transactions.
Mock contracts allow you to:
- Test your application logic without deploying to mainnet
- Avoid transaction fees during development
- Add testing-specific functionality (like public minting)
- Maintain the same interface as the production contract
Your mock contract must use the exact same name as the mainnet contract.
// ❌ Wrong - Different contract name
access(all) contract USDF_MOCK: FungibleToken {
// ✅ Correct - Same name as mainnet
access(all) contract EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabed: FungibleToken {Use the exact same storage and public paths as the mainnet contract.
// In init(), use the same paths as mainnet
self.VaultStoragePath = /storage/EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabedVault
self.VaultPublicPath = /public/EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabedVault
self.ReceiverPublicPath = /public/EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabedReceiverImplement the same public functions and resources as the mainnet contract, or provide compatible alternatives.
// Ensure your mock has the same public interface
access(all) resource Vault: FungibleToken.Vault {
// Same methods as mainnet contract
access(all) var balance: UFix64
access(all) fun deposit(from: @{FungibleToken.Vault})
access(FungibleToken.Withdraw) fun withdraw(amount: UFix64): @{FungibleToken.Vault}
// ... other required methods
}Configure your flow.json to use network aliases that point to different addresses:
{
"contracts": {
"EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabed": {
"source": "cadence/contracts/USDF_MOCK.cdc",
"aliases": {
"emulator": "f8d6e0586b0a20c7",
"testnet": "0x...",
"mainnet": "1e4aa0b87d10b141"
}
}
}
}Since mainnet contracts may not expose path constants publicly, use hard-coded paths in your scripts and transactions:
// ✅ Use hard-coded paths that work on all networks
if let vaultRef = accountRef.capabilities.borrow<&ContractName.Vault>(
/public/EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabedVault
) {
return vaultRef.balance
}- Find the contract address and name on Flow blockchain explorers
- Examine the contract's public interface using scripts
- Identify the storage paths used by the contract
- Note the token metadata (name, symbol, decimals)
- Name your contract exactly the same as mainnet
- Implement the same interfaces (e.g.,
FungibleTokenfor tokens) - Use identical storage paths from the mainnet contract
- Add testing conveniences like public minting functions
- Maintain interface compatibility for all public methods
- Add your contract with the mainnet name
- Set up network aliases pointing to appropriate addresses
- Include necessary dependencies (FungibleToken, MetadataViews, etc.)
- Remove unused dependencies to keep the configuration clean
- Import the contract using its mainnet name
- Use hard-coded storage paths instead of contract constants
- Handle network differences gracefully (e.g., different metadata access methods)
- Test on both networks to ensure compatibility
Here's how we implemented a USDF mock contract:
access(all) contract EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabed: FungibleToken {
// Same storage paths as mainnet
access(all) let VaultStoragePath: StoragePath
access(all) let VaultPublicPath: PublicPath
access(all) let ReceiverPublicPath: PublicPath
// Mock-specific: Public mint function for testing
access(all) fun mintTokens(amount: UFix64): @{FungibleToken.Vault} {
// Testing convenience not available on mainnet
}
init() {
// Use identical paths to mainnet
self.VaultStoragePath = /storage/EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabedVault
self.VaultPublicPath = /public/EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabedVault
self.ReceiverPublicPath = /public/EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabedReceiver
}
}import "EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabed"
access(all) fun main(account: Address): UFix64 {
let accountRef = getAccount(account)
// Hard-coded path works on all networks
if let vaultRef = accountRef.capabilities.borrow<&EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabed.Vault>(
/public/EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabedVault
) {
return vaultRef.balance
}
return 0.0
}{
"contracts": {
"EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabed": {
"source": "cadence/contracts/USDF_MOCK.cdc",
"aliases": {
"emulator": "f8d6e0586b0a20c7",
"mainnet": "1e4aa0b87d10b141"
}
}
},
"deployments": {
"emulator": {
"emulator-account": ["EVMVMBridgedToken_2aabea2058b5ac2d339b163c6ab6f2b6d53aabed"]
}
}
}# Deploy your mock contract
flow project deploy --network emulator
# Test scripts and transactions
flow scripts execute path/to/script.cdc --network emulator
flow transactions send path/to/transaction.cdc --network emulator --signer account# Test scripts (read-only, no deployment needed)
flow scripts execute path/to/script.cdc --network mainnet
# Transactions will use the real mainnet contract
flow transactions send path/to/transaction.cdc --network mainnet --signer account// This won't work with network aliases
access(all) contract MyTokenMock: FungibleToken {// This may fail on mainnet if the contract doesn't expose these constants
if let vault = account.borrow<&Vault>(MyContract.VaultStoragePath) {// Mainnet contract might not have this method
let decimals = MyContract.getDecimals() // May fail on mainnet// This works on all networks
if let vault = account.borrow<&Vault>(/storage/MyContractVault) {// Fallback to metadata views if direct methods don't exist
let ftView = MyContract.resolveContractView(/* ... */) as! FungibleTokenMetadataViews.FTDisplay?
let decimals = ftView?.decimals ?? 6 // Fallback value- Single Codebase: One set of scripts/transactions for all networks
- Easy Testing: Mock contracts can have testing conveniences like public minting
- Production Ready: Same scripts work seamlessly on mainnet
- Cost Effective: No transaction fees during development on emulator
- Realistic Testing: Mock maintains same interface and behavior as production
By following these rules and patterns, you can create mock contracts that provide a seamless development experience across different Flow networks. The key is maintaining interface compatibility while leveraging Flow's network alias system to automatically point to the right contract on each network.