Troubleshooting

Contract Not Being Executed

Symptom: Your contract is registered but workers aren't calling progressLoop().

Check these in order:

1. Is shouldProgressLoop() returning true?

cast call $YOUR_CONTRACT "shouldProgressLoop()" --rpc-url $RPC_URL

If it returns false, your readiness condition isn't met yet (e.g., not enough time has passed, game state not ready).

1. Is your contract funded?

Workers skip contracts with insufficient balance. Check your balance on the dashboard or directly:

cast call $REGISTRY "getBalance(address)" $YOUR_CONTRACT --rpc-url $RPC_URL

Deposit more ETH if needed. A good starting balance is 0.01–0.1 ETH depending on tick frequency.

1. Is the contract registered?

cast call $REGISTRY "isRegistered(address)" $YOUR_CONTRACT --rpc-url $RPC_URL

1. Are workers running?

Check the status page to see active workers. If no workers are online, loops won't execute.

VRF Proofs Failing

Symptom: VRF or Hybrid VRF contract reverts with proof verification errors.

Causes:

1. Controller public key not registered. Each worker's secp256k1 public key (pkX, pkY) must be registered on the VRF contract before it can submit proofs. See Testing Guide for key derivation.

2. Wrong key registered. The pkX/pkY must correspond to the private key the worker is actually using. If you rotated keys, re-register.

3. Contract expects different VRF interface. Make sure your contract inherits the correct base:

   • AutoLoopVRFCompatible for every-tick VRF
   • AutoLoopHybridVRFCompatible for selective VRF

Transaction Reverts

Symptom: Worker logs show reverted transactions.

Common causes:

Hybrid VRF: needsVRF Not Working

Symptom: Your Hybrid contract always gets VRF (or never gets VRF).

Check:

1. Make sure you're setting the needsVRF flag correctly in your contract logic — workers read this flag before each tick.

2. The flag must be set before the worker calls shouldProgressLoop(). If you set it inside progressLoop(), it's too late for the current tick.

// Correct: set flag in your game state update
function _updateGameState() internal {
    turnCount++;
    // Request VRF for every 10th turn
    needsVRF = (turnCount % 10 == 0);
}

Local Anvil Issues

Anvil won't start

Make sure no other process is using port 8545:

lsof -i :8545  # macOS/Linux
netstat -ano | findstr 8545  # Windows

Worker can't connect to Anvil

Ensure your .env points to the correct URL:

RPC_URL=http://127.0.0.1:8545
NETWORK=anvil

Contract deploys but worker ignores it

The worker only monitors contracts registered in the AutoLoopRegistry. Make sure you:

1. Deployed the registry and registrar
2. Registered your contract via the registrar
3. The worker's NETWORK env var matches your Anvil config

Dashboard Can't Find My Contract

Symptom: Dashboard shows no contracts or can't detect your contract.

1. Make sure your wallet is connected to the correct network (Mainnet or Sepolia)
2. Your contract must be registered through the Registrar — the dashboard reads from the Registry
3. If you just registered, wait a few seconds for the next block and refresh

Gas Costs Higher Than Expected

AutoLoop adds overhead on top of your contract's progressLoop() gas:

• Gas buffer: 94,293 gas for protocol overhead (fee calculation, access checks, event emissions)
• Base fee: 70% of total gas cost, split between protocol and controller

If your progressLoop() uses 50,000 gas, the total transaction will use approximately:

50,000 (your logic) + 94,293 (buffer) = ~144,293 gas
Total cost to contract = gas cost × 1.7 (gas + 70% base fee)

To reduce costs:

• Minimize storage writes in progressLoop()
• Use events instead of storage where possible
• Consider Hybrid VRF instead of Full VRF if you don't need randomness every tick

Getting Help

• Check the status page for network health
• Review the API reference for contract interfaces
• File an issue on GitHub