gh-enviodev-envio-plugins-plugins-envio-hyperindex/skills/hyperindex-development/references/reorg-support.md

Chain Reorganization (Reorg) Support

HyperIndex automatically handles chain reorganizations to keep your indexed data consistent with the blockchain's canonical state.

What Are Reorgs?

Chain reorganizations occur when the blockchain temporarily forks and then resolves to a single chain. When this happens:

• Some previously confirmed blocks get replaced
• Transactions may be dropped or reordered
• Indexed data may no longer be valid

HyperIndex detects reorgs and automatically rolls back affected data.

Configuration

Enable/Disable (Default: Enabled)

# config.yaml
rollback_on_reorg: true   # Default - recommended for production

Confirmation Threshold

Configure how many blocks must pass before data is considered "final":

# config.yaml
rollback_on_reorg: true
networks:
  - id: 1        # Ethereum
    confirmed_block_threshold: 250   # Higher for Ethereum mainnet

  - id: 137      # Polygon
    confirmed_block_threshold: 150   # Lower for faster chains

  - id: 42161    # Arbitrum
    # Uses default: 200 blocks

Default threshold: 200 blocks for all networks.

What Gets Rolled Back

When a reorg is detected:

Rolled Back	NOT Rolled Back
All entity data	External API calls
Schema entities	Webhooks sent
Database writes	Logs written to files
	Analytics events

Example Configuration

# Production config with reorg handling
name: my-indexer
rollback_on_reorg: true

networks:
  - id: 1          # Ethereum Mainnet
    confirmed_block_threshold: 250
    start_block: 18000000
    contracts:
      - name: MyContract
        address: "0x..."
        handler: src/EventHandlers.ts
        events:
          - event: Transfer(address indexed from, address indexed to, uint256 value)

  - id: 10         # Optimism
    confirmed_block_threshold: 100   # Faster finality
    start_block: 100000000
    contracts:
      - name: MyContract
        address: "0x..."
        handler: src/EventHandlers.ts
        events:
          - event: Transfer(address indexed from, address indexed to, uint256 value)

Best Practices

1. Keep Reorg Support Enabled

rollback_on_reorg: true  # Always for production

Only disable for development/testing when you need faster iteration.

2. Use HyperSync for Guaranteed Detection

Reorg detection is guaranteed when using HyperSync (the default data source).

With custom RPC endpoints, edge cases may go undetected depending on the provider.

3. Avoid Non-Rollbackable Side Effects

// BAD - Can't be rolled back if reorg happens
MyContract.Event.handler(async ({ event, context }) => {
  await sendWebhook(event);  // This stays even if block is reorged
  await postToAnalytics(event);
});

// BETTER - Use Effect API with caching
// Or guard side effects appropriately
MyContract.Event.handler(async ({ event, context }) => {
  // Entity writes ARE rolled back
  context.Transfer.set({
    id: `${event.chainId}_${event.transactionHash}_${event.logIndex}`,
    // ...
  });

  // For critical external calls, consider confirmation delay
  // or handle in a separate system that reads from your indexed data
});

4. Higher Thresholds for High-Value Apps

For financial applications or high-stakes data:

networks:
  - id: 1
    confirmed_block_threshold: 300  # Extra conservative

5. Adjust Per Network

Different networks have different reorg characteristics:

Network	Typical Reorg Depth	Recommended Threshold
Ethereum	Rare, shallow	200-300
Polygon	More frequent	150-200
Arbitrum	Very rare (L2)	100-150
Optimism	Very rare (L2)	100-150
BSC	Occasional	150-200

Reorg Handling in Code

You generally don't need special code for reorgs - HyperIndex handles it automatically. However, be aware:

MyContract.Event.handler(async ({ event, context }) => {
  // This entity write will be rolled back if the block is reorged
  context.Transfer.set({
    id: `${event.chainId}_${event.block.number}_${event.logIndex}`,
    from: event.params.from,
    to: event.params.to,
    amount: event.params.value,
    // Include block info for debugging
    blockNumber: BigInt(event.block.number),
    blockHash: event.block.hash,
  });
});

Debugging Reorg Issues

If you suspect reorg-related data inconsistencies:

1. Check if rollback_on_reorg: true is set
2. Verify you're using HyperSync (not custom RPC)
3. Check block explorer for the affected block range
4. Look for "reorg detected" in indexer logs

Summary

Setting	Value	Use Case
rollback_on_reorg	true	Production (default)
rollback_on_reorg	false	Dev/testing only
confirmed_block_threshold	200	Default for all networks
confirmed_block_threshold	250-300	High-value Ethereum apps
confirmed_block_threshold	100-150	L2s with fast finality