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?

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

1. Is chain ID correct?

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

1. Verify signature recovery:

``bash # 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)