---

name: brane-debugging description: Systematic approach to debugging Brane SDK issues. Use when diagnosing transaction failures, RPC errors, encoding mismatches, or unexpected behavior.

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

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

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

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

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

Verify calldata manually:

Copy# 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?

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

2. Is chain ID correct?

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

3. Verify signature recovery:

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

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

Get revert reason:

Copytry {
    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)

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

Decode:

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

Panic Code (0x4e487b71)

Copy0x4e487b71
0000000000000000000000000000000000000000000000000000000000000011  // panic code

Custom Error

Copy0x<4-byte-selector><encoded-params>

Find selector:

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

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

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

Verify Encoded Parameters

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

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

Common Encoding Mistakes

---

Debugging with Anvil

Start Anvil with Logging

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

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

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

---

Debugging Contract Binding

Method Not Found

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

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

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

Copy// 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

Copy// 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)