explorer-monorepo/docs/NETWORK_PERMISSIONS_RESOLUTION_GUIDE.md

# Network Permissions Resolution Guide

**Date**: 2025-01-12  
**Purpose**: Complete guide to resolving contract deployment issues on ChainID 138

---

## Executive Summary

**Status**: ⚠️ **ALL contract deployments are failing** despite:
- ✅ Account permissioning is DISABLED on Core RPC
- ✅ permissions-accounts.toml is EMPTY (all accounts allowed)
- ✅ Deployer has sufficient balance (999M+ ETH)
- ✅ Network is operational (blocks are being produced)

**Root Cause**: Unknown - requires network administrator investigation

---

## Diagnostic Results

### 1. RPC Endpoint Status

| RPC Type | IP Address | Status | Account Permissioning |
|----------|------------|--------|----------------------|
| **Core RPC** | 192.168.11.250 | ✅ Accessible | DISABLED |
| **Permissioned RPC** | 192.168.11.251 | ❌ Not accessible | ENABLED |
| **Public RPC** | 192.168.11.252 | ❌ Not accessible | DISABLED |

### 2. Configuration Analysis

#### Account Permissioning
- **File**: `smom-dbis-138/config/permissions-accounts.toml`
- **Status**: EMPTY (all accounts allowed)
- **Note**: Empty allowlist means all accounts are permitted

#### RPC Node Configurations
- **Core RPC**: `permissions-accounts-config-file-enabled=false` ✅
- **Permissioned RPC**: `permissions-accounts-config-file-enabled=true` ⚠️
- **Public RPC**: `permissions-accounts-config-file-enabled=false` ✅

### 3. Deployment Test Results

All deployment attempts have failed:
- MockLinkToken (5M gas): ❌ FAILED
- MockLinkToken (10M gas): ❌ FAILED
- MinimalLink (10M gas): ❌ FAILED
- Minimal Test Contract (204 bytes, 1M gas): ❌ FAILED

**Pattern**: All transactions use all available gas and revert (status 0x0)

---

## Resolution Steps

### Step 1: Verify RPC Node Configuration

Check if the actual RPC node configuration matches the expected settings:

```bash
# SSH into RPC node (if accessible)
ssh root@192.168.11.250

# Check Besu configuration
cat /etc/besu/config-rpc-core.toml | grep permissions-accounts

# Check if permissions-accounts.toml exists and is empty
cat /etc/besu/permissions-accounts.toml
```

**Expected Result**:
- `permissions-accounts-config-file-enabled=false` (Core RPC)
- `permissions-accounts.toml` should be empty or not exist

### Step 2: Check Besu Logs

Review Besu logs for deployment errors:

```bash
# Check Besu service logs
journalctl -u besu-rpc -n 200 --no-pager

# Or if using Docker
docker logs besu-rpc --tail 200

# Look for transaction-related errors
journalctl -u besu-rpc | grep -iE "transaction|reject|invalid|revert|gas"
```

**What to Look For**:
- Transaction rejection messages
- Gas limit errors
- Permission denied errors
- Contract creation restrictions

### Step 3: Verify Network-Level Restrictions

Check if contract creation is restricted at the network level:

```bash
# Check genesis file for restrictions
jq '.config' smom-dbis-138-proxmox/config/genesis.json

# Check for any network-level restrictions
grep -i "restrict\|permission\|allowlist" smom-dbis-138-proxmox/config/genesis.json
```

### Step 4: Test with Different Deployment Methods

Try alternative deployment methods:

#### Method 1: Direct Validator Deployment
```bash
# Deploy via validator node (if accessible)
# Validators typically have full permissions
```

#### Method 2: Remix IDE
```bash
# Use Remix IDE with network admin access
# Connect to RPC: http://192.168.11.250:8545
# Deploy contract via Remix interface
```

#### Method 3: Network Administrator
```bash
# Request network administrator to deploy
# Provide contract bytecode and constructor parameters
```

### Step 5: Add Deployer to Account Allowlist (If Needed)

If account permissioning is enabled on the actual RPC node:

```bash
# Edit permissions-accounts.toml
nano /etc/besu/permissions-accounts.toml

# Add deployer address:
accounts-allowlist=[
  "0x4A666F96fC8764181194447A7dFdb7d471b301C8"
]

# Restart Besu service
systemctl restart besu-rpc
```

---

## Troubleshooting Checklist

- [ ] Verify RPC node configuration matches expected settings
- [ ] Check Besu logs for deployment errors
- [ ] Verify network allows contract creation
- [ ] Test with minimal contract (204 bytes)
- [ ] Check if deployer account needs whitelisting
- [ ] Verify RPC node is fully synced
- [ ] Check network genesis for restrictions
- [ ] Test with alternative RPC endpoint
- [ ] Contact network administrators

---

## Network Administrator Contact

If the issue persists after completing all troubleshooting steps:

1. **Provide Diagnostic Report**:
   - Run `scripts/comprehensive-network-diagnostic.sh`
   - Share output with network administrators

2. **Request Investigation**:
   - Verify if contract creation is restricted
   - Check if deployer account needs whitelisting
   - Review network policies and Besu configuration

3. **Request Deployment**:
   - Provide contract bytecode
   - Request network administrator to deploy
   - Verify deployment after completion

---

## Alternative Solutions

### Solution 1: Use Pre-deployed Contracts

If contract creation is permanently restricted:
- Use existing contracts on the network
- Deploy contracts on a different network
- Use proxy contracts for upgrades

### Solution 2: Network Fork

If contract creation is required:
- Fork the network with contract creation enabled
- Deploy contracts on the fork
- Merge changes back to main network

### Solution 3: Validator Deployment

If validators have deployment permissions:
- Request validator to deploy contracts
- Provide contract bytecode and parameters
- Verify deployment after completion

---

## Scripts Created

1. **`scripts/verify-rpc-permissions.sh`**
   - Verifies RPC node account permissioning configuration
   - Checks if deployer is whitelisted

2. **`scripts/comprehensive-network-diagnostic.sh`**
   - Complete network diagnostic
   - Tests all RPC endpoints
   - Analyzes configuration and recent transactions

---

## Documentation

- `docs/NETWORK_PERMISSIONS_CHECK.md` - Initial analysis
- `docs/NETWORK_PERMISSIONS_FINAL_ANALYSIS.md` - Complete analysis
- `docs/NETWORK_PERMISSIONS_RESOLUTION_GUIDE.md` - This guide

---

**Last Updated**: 2025-01-12