smom-dbis-138/docs/deployment/REAL_TIME_GAS_SYSTEM.md

# Real-Time Gas Price System

**Last Updated**: 2025-01-27

## Overview

The multichain deployment system now includes **real-time gas price fetching** using APIs configured in your `.env` file. This ensures all cost estimates are based on current market conditions, not outdated static values.

## Quick Start

```bash
# 1. Ensure .env is configured with API keys and RPC URLs
# 2. Fetch real-time gas prices
./scripts/deployment/get-multichain-gas-prices.sh

# 3. Update all documentation
./scripts/deployment/update-gas-estimates.sh
```

## What Gets Updated

The system updates the following documentation files with real-time gas prices:

1. **`GAS_AND_TOKEN_REQUIREMENTS.md`**
   - Gas price tables for all chains
   - Cost estimates in native tokens
   - USD cost estimates
   - Recommended balances

2. **`TOKENS_AND_CHAINS_SUMMARY.md`**
   - Recommended token balances
   - Cost estimates per chain
   - Total deployment costs

3. **`DEPLOYMENT_QUICK_REFERENCE.md`**
   - Quick reference tables
   - Minimum balances
   - Cost estimates

## How It Works

### 1. Gas Price Fetching

The `get-multichain-gas-prices.sh` script:

- **Ethereum Mainnet**: Uses Etherscan Gas API v2 (via `ETHERSCAN_API_KEY`)
- **Other Chains**: Uses RPC `eth_gasPrice` calls (via `*_RPC_URL` variables)
- **Fallbacks**: Uses sensible defaults if APIs are unavailable

### 2. Cost Calculation

For each chain:
```
Cost (Native Token) = (Gas Units × Gas Price in Wei) / 10^18
Cost (USD) = Cost (Native Token) × Token Price (USD)
```

### 3. Documentation Updates

The `update-gas-estimates.sh` script:
- Reads gas price data from the fetcher
- Updates all markdown files with current values
- Updates timestamps
- Maintains formatting and structure

## Configuration

### Required in `.env`

```bash
# Ethereum Mainnet (for Etherscan API)
ETHERSCAN_API_KEY=your_api_key_here
ETH_MAINNET_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY

# Other Chains (RPC endpoints)
CRONOS_RPC_URL=https://evm.cronos.org
BSC_RPC_URL=https://bsc-dataseed1.binance.org
POLYGON_RPC_URL=https://polygon-rpc.com
GNOSIS_RPC_URL=https://rpc.gnosischain.com
```

### Optional

```bash
# Infura Gas API (alternative to Etherscan)
INFURA_GAS_API=your_infura_api_key_here
```

## Example Output

```
========================================
Multichain Gas Price Fetcher
========================================

Chain ID: 1
Deployer: 0x...
Deployer Balance: 0.5 ETH/Native

Fetching real-time gas prices...
✓ Gas prices fetched

Current Gas Prices:
  Ethereum Mainnet: 25.5 gwei
  Cronos: 1.2 gwei
  BSC: 3.5 gwei
  Polygon: 45.0 gwei
  Gnosis: 2.1 gwei

Deployment Cost Estimates:

Ethereum Mainnet (CCIPLogger only):
  Gas: 3000000 units
  Cost: 0.0765 ETH (~$191.25)

Cronos (all 5 contracts):
  Gas: 8760000 units
  Cost: 10.512 CRO (~$0.84)

...

Total Estimated Cost: ~$520.05 USD

✓ Gas prices saved to /tmp/multichain_gas_prices.json
```

## Integration

### Pre-Deployment Workflow

```bash
#!/bin/bash
# Pre-deployment checklist

# 1. Fetch real-time gas prices
./scripts/deployment/get-multichain-gas-prices.sh

# 2. Check if costs are acceptable
ETH_COST=$(jq -r '.gas_prices.ethereum_mainnet.cost_eth' /tmp/multichain_gas_prices.json)
if (( $(echo "$ETH_COST > 0.20" | bc -l) )); then
    echo "⚠️  Gas costs are high. Consider waiting."
    exit 1
fi

# 3. Update documentation
./scripts/deployment/update-gas-estimates.sh

# 4. Proceed with deployment
echo "✓ Gas costs acceptable. Proceeding..."
```

### CI/CD Integration

Add to your deployment pipeline:

```yaml
# .github/workflows/deploy.yml
- name: Fetch Real-Time Gas Prices
  run: |
    ./scripts/deployment/get-multichain-gas-prices.sh
    ./scripts/deployment/update-gas-estimates.sh
```

## Benefits

1. **Accurate Estimates**: Always uses current market prices
2. **Automated Updates**: No manual calculation needed
3. **Multi-Chain Support**: Fetches prices for all 5 chains
4. **Documentation Sync**: Keeps all docs in sync automatically
5. **Programmatic Access**: JSON output for scripts/automation

## Troubleshooting

### Script Fails

1. **Check API Keys**: `echo $ETHERSCAN_API_KEY`
2. **Test RPC Endpoints**: `cast gas-price --rpc-url $ETH_MAINNET_RPC_URL`
3. **Check Network**: `ping -c 1 api.etherscan.io`

### Documentation Not Updating

1. **Check Permissions**: `ls -la docs/deployment/*.md`
2. **Verify JSON**: `cat /tmp/multichain_gas_prices.json`
3. **Run Manually**: Execute scripts step by step

## Related Documentation

- [Real-Time Gas Updates](./REAL_TIME_GAS_UPDATES.md) - Detailed guide
- [Gas and Token Requirements](./GAS_AND_TOKEN_REQUIREMENTS.md) - Cost breakdown
- [Multichain Deployment Runbook](./MULTICHAIN_DEPLOYMENT_RUNBOOK.md) - Deployment guide

---

**Last Updated**: 2025-01-27