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:

# 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:

# 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:

# 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

# Deploy via validator node (if accessible)
# Validators typically have full permissions

Method 2: Remix IDE

# 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

# 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:

# 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