Brane Debugging

Brane SDK Debugging Guide

Debugging Philosophy

1. Reproduce first - Get a minimal reproduction
2. Isolate the layer - RPC? Encoding? Signing? Contract?
3. Compare with known-good - Use Anvil, compare with viem/cast
4. Read the actual bytes - Hex doesn't lie

Quick Diagnosis Flowchart

Transaction Failed
       │
       ▼
┌─────────────────┐
│ What error?     │
└────────┬────────┘
         │
    ┌────┴────┬────────────┬─────────────┐
    ▼         ▼            ▼             ▼
"reverted"  "nonce"    "gas"      "insufficient
    │         │          │         funds"
    ▼         ▼          ▼             │
 Decode     Check      Estimate       ▼
 revert    pending      gas        Check
 data       txs                   balance

Layer-by-Layer Debugging

Layer 1: RPC Communication

Symptoms: Connection refused, timeout, unexpected null

Checks:

# Is the node reachable?
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

# Expected: {"jsonrpc":"2.0","id":1,"result":"0x1"}

Common Issues:

Layer 2: Request Encoding

Symptoms: Invalid params error, unexpected behavior

Debug Approach:

// Enable Brane debug logging
System.setProperty("BRANE_DEBUG", "true");

// This will print:
// [BRANE] → eth_call {"to":"0x...", "data":"0x..."}
// [BRANE] ← "0x..."

Verify calldata manually:

# Using cast (foundry)
cast calldata "balanceOf(address)" 0xYourAddress

# Compare with what Brane generates

Layer 3: Transaction Signing

Symptoms: Invalid sender, signature error

Checks:

1. Is the signer address what you expect?

   System.out.println("Signer address: " + signer.address());
   

2. Is chain ID correct?

   // Chain ID mismatch causes "invalid sender"
   var chainId = publicClient.getChainId();
   System.out.println("Chain ID: " + chainId);
   

3. Verify signature recovery:

   # Using cast
   cast wallet sign --private-key 0x... "message"
   

Layer 4: Contract Execution

Symptoms: Revert, out of gas, unexpected return value

Debug with eth_call first:

// Test without sending transaction
var result = publicClient.call(TransactionRequest.builder()
    .to(contractAddress)
    .data(encodedCalldata)
    .build());

Get revert reason:

try {
    walletClient.sendTransaction(request);
} catch (RevertException e) {
    System.out.println("Revert kind: " + e.kind());
    System.out.println("Reason: " + e.reason());
    System.out.println("Raw data: " + e.rawDataHex());
}

Decoding Revert Data

Standard Error (0x08c379a0)

0x08c379a0
0000000000000000000000000000000000000000000000000000000000000020  // offset
0000000000000000000000000000000000000000000000000000000000000011  // length (17)
496e73756666696369656e742066756e647300000000000000000000000000  // "Insufficient funds"

Decode:

cast 4byte-decode 0x08c379a0...
# Or
cast --to-ascii 0x496e73756666696369656e742066756e6473

Panic Code (0x4e487b71)

0x4e487b71
0000000000000000000000000000000000000000000000000000000000000011  // panic code

Custom Error

0x<4-byte-selector><encoded-params>

Find selector:

# If you have the ABI
cast sig "InsufficientBalance(uint256,uint256)"
# Returns: 0x...

# Or search online
# https://openchain.xyz/signatures

Common Error Messages

Transaction Errors

RPC Errors

eth_call Errors

Debugging ABI Encoding

Verify Function Selector

// What Brane computes
var selector = Abi.computeSelector("transfer(address,uint256)");
System.out.println("Selector: " + Hex.encode(selector));
// Should be: 0xa9059cbb

# Verify with cast
cast sig "transfer(address,uint256)"

Verify Encoded Parameters

// Print full calldata
var calldata = abi.encodeFunction("transfer", recipient, amount);
System.out.println("Calldata: " + calldata.value());

# Decode to verify
cast calldata-decode "transfer(address,uint256)" 0xa9059cbb...

Common Encoding Mistakes

Debugging with Anvil

Start Anvil with Logging

# Verbose mode shows all RPC calls
anvil -vvvv

# Fork mainnet for testing against real contracts
anvil --fork-url https://eth.llamarpc.com

Useful Anvil Commands

# Mine a block
cast rpc anvil_mine

# Set balance
cast rpc anvil_setBalance 0xAddress 0x1000000000000000000

# Impersonate account
cast rpc anvil_impersonateAccount 0xWhale

# Get transaction trace
cast run <txhash> --trace

Compare with Cast

# Send same transaction with cast, compare results
cast send --private-key 0x... \
  0xContractAddress \
  "transfer(address,uint256)" \
  0xRecipient \
  1000000

Debugging Contract Binding

Method Not Found

IllegalArgumentException: No ABI function named 'transfer'

Checks:

1. Method name matches ABI exactly (case-sensitive)
2. ABI JSON is valid and contains the function
3. Interface method matches ABI signature

Parameter Type Mismatch

IllegalArgumentException: Unsupported parameter type for transfer

Checks:

1. Java type matches Solidity type
2. For arrays: use List<T> or T[]
3. For uint256: use BigInteger, not long

Return Type Mismatch

IllegalArgumentException: Unsupported return type for view function

Checks:

1. View functions return the decoded type
2. State-changing functions return TransactionReceipt or void

Debug Logging

Enable Brane Debug Output

// Set before any Brane calls
System.setProperty("BRANE_DEBUG", "true");

Output includes:

• RPC method and parameters
• Response data
• Transaction encoding details
• Gas estimation

Custom Logging Points

// Log transaction request
System.out.println("To: " + request.to());
System.out.println("Data: " + request.data());
System.out.println("Value: " + request.value());

// Log raw signed transaction
System.out.println("Signed: " + Hex.encode(signedTx));

Network-Specific Issues

Mainnet

• Rate limits from public RPCs
• High gas prices during congestion
• MEV/frontrunning effects

Testnets

• Faucet rate limits
• Occasional reorgs
• Different behavior than mainnet

L2s (Arbitrum, Optimism, Base)

• Different gas model
• Sequencer delays
• L1 data costs in gas

Checklist: Transaction Won't Send

1. Node reachable? (eth_chainId works?)
2. Correct chain ID?
3. Sender has balance for gas + value?
4. Nonce is correct? (fetch with "pending")
5. Gas limit sufficient? (try eth_estimateGas)
6. Gas price acceptable? (not below minimum)
7. Contract address correct?
8. Function selector correct?
9. Parameters encoded correctly?
10. Signer address matches expected?

Checklist: eth_call Returns Wrong Data

1. Contract address correct?
2. Function exists in contract?
3. Selector matches? (compare with cast sig)
4. Parameters encoded correctly?
5. Return type matches ABI?
6. Block parameter correct? (latest vs specific)
7. Contract not proxy? (might need implementation address)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.