debug-user-tx

You are debugging a transaction that a user reports as failing. You have the project's source code locally; the goal is to reproduce the failure against forked cluster state, then map the on-chain error back to the exact line of Rust / IDL that produced it and suggest a fix.

Related Skills

• ext/solana-dev/skill/references/testing.md — Surfpool (mainnet fork), LiteSVM, Mollusk
• ext/solana-dev/skill/references/programs/anchor.md — Anchor error codes, constraint failures
• ext/solana-dev/skill/references/programs/pinocchio.md — Pinocchio error patterns
• ext/solana-dev/skill/references/security.md — Common failure categories

Inputs

Collect from the user (at least one of signature or instruction is required):

Input	Required	Notes
signature	preferred	On-chain tx signature. Fastest path — fetch + replay.
wallet	optional	User's pubkey. Auto-extracted from tx if signature given.
instruction	fallback	Raw ix JSON when the tx never landed (serialized tx / accounts + data).
cluster	optional	mainnet / devnet. Default: infer from Anchor.toml or .env.
rpc	optional	Override RPC endpoint. Default: cluster default or project .env.
program	optional	Program ID. Auto-detected from workspace.

If the user only pasted an error message, ask for the signature before proceeding — it's the difference between 30 seconds and guessing.

Step 1: Detect Project Layout

echo "Detecting project..."

FRAMEWORK="unknown"
if [ -f "Anchor.toml" ]; then
    FRAMEWORK="anchor"
    echo "Anchor project detected"
elif [ -f "Cargo.toml" ] && grep -q "pinocchio" Cargo.toml 2>/dev/null; then
    FRAMEWORK="pinocchio"
    echo "Pinocchio project detected"
elif [ -f "Cargo.toml" ] && grep -q "solana-program" Cargo.toml 2>/dev/null; then
    FRAMEWORK="native"
    echo "Native Solana program detected"
else
    echo "No Solana program workspace detected. Debug will proceed RPC-only (no source mapping)."
fi

# Infer cluster
CLUSTER="${CLUSTER:-mainnet}"
if [ -f "Anchor.toml" ]; then
    DETECTED=$(grep -m1 'cluster' Anchor.toml | sed 's/.*= *//' | tr -d '"')
    [ -n "$DETECTED" ] && CLUSTER="$DETECTED"
fi
echo "Cluster: $CLUSTER"

# Collect program IDs + IDLs
ls target/idl/*.json 2>/dev/null || echo "No IDLs found at target/idl/ — run 'anchor build' for best results"