mvx-debug-tx

Files (1)

• SKILL.md

SKILL.md (first lines)

# MultiversX Transaction Debugger

Analyze a transaction to determine what happened, why it failed (if applicable), decode all smart contract outputs, and explain every event. Combines on-chain decoding with local simulation techniques.

## Phase 1: Fetch Transaction Data

### 1.1 Get Full Transaction Results

Retrieve the complete transaction data from the MultiversX API.

**Manual approach**: Query the API directly:
```
GET https://gateway.multiversx.com/transaction/{txHash}?withResults=true
```
Or use the explorer: `https://explorer.multiversx.com/transactions/{txHash}`

For devnet/testnet, replace the base URL accordingly (`devnet-api.multiversx.com`, `testnet-api.multiversx.com`).

**MCP shortcut**: If a MultiversX MCP server is available (multiversx-sc-mcp or multiversx-mcp-server), use `mvx_tx_result` for this step.

Extract and record:
- **Status**: success, fail, or pending
- **Sender**: who initiated the transaction
- **Receiver**: the target address (contract or EOA)
- **Value**: EGLD amount sent (if any)
- **Data field**: the raw transaction data (function call + arguments)
- **Gas limit**: gas allocated
- **Gas used**: gas actually consumed
- **Gas refund**: gas returned to sender
- **Timestamp**: when the transaction was processed
- **Block / Nonce**: transaction ordering info
- **Miniblock hash**: for cross-shard tracking

### 1.2 Decode the Data Field

The transaction data field contains the function call. Parse it:
- First component (before `@`): function name (plain text ASCII)
- Subsequent `@`-separated components: arguments (hex-encoded)

For each argument, determine:

| Position | Hex Value | Decoded Value | Likely Type |
|----------|-----------|---------------|-------------|
| arg0 | ... | ... | Address / BigUint / TokenIdentifier / ... |

**Decoding tips**:
- Addresses: 64 hex chars, decode to bech32 `erd1...` format
- BigUint: variable-length hex, convert to decimal
- TokenIdentifier: hex-decode to ASCII string (e.g., `4d45582d343535633537` = `MEX-455c57`)
- Nested/complex types: refer to the contract ABI for struct layouts

**MCP shortcut**: If a MultiversX MCP server is available (multiversx-sc-mcp or multiversx-mcp-server), use `mvx_sc_decode` to decode complex argument types (structs, enums, nested types).

### 1.3 Identify Token Transfers

If the transaction includes ESDT transfers (ESDTTransfer, ESDTNFTTransfer, MultiESDTNFTTransfer):
- Decode the token identifier, nonce (for NFTs/SFTs), and amount
- Note: MultiESDTNFTTransfer has a different argument layout (destination first, then count, then token triplets)

## Phase 2: Analyze Results

### 2.1 Smart Contract Results (SCRs)

For each smart contract result in the transaction:
- **Direction**: which contract generated it, who receives it
- **Data**: decode the return data
  - `@6f6b` = `@ok` (success)
  - `@` followed by error code = failure
  - Multiple `@`-separated values = multi-return
- **Value / Tokens**: any EGLD or ESDT transfers in the result
- **Gas**: gas forwarded and consumed

Build a call trace showing the execution flow:

```
1. Sender -> Contract A: functionName(args...)
   1.1 Contract A -> Contract B: innerCall(args...)
       Result: [decoded return value]
   1.2 Contract A -> Sender: [token transfer / refund]
   Result: [ok / error]
```

### 2.2 Decode Return Values

If the transaction succeeded and returned data:
- Use the contract ABI to match return types to the endpoint signature
- Decode multi-value returns by splitting on `@` separators

**MCP shortcut**: If a MultiversX MCP server is available (multiversx-sc-mcp or multiversx-mcp-server), use `mvx_sc_abi` on the receiver address to fetch the ABI, and `mvx_sc_decode` to decode return values.

### 2.3 Failure Analysis

If the transaction failed, identify the root cause.

**Common failure patterns**:

| Error Message | Meaning | Likely Cause |
|---------------|---------|--------------|
| `execution failed` | SC logic error | require/sc_panic triggered |
| `out of gas` | Insufficient gas | Complex operation or gas limit too low |
| `user error` | Input validation | Wrong arguments, wrong token, insufficient balance |
| `signal error` | SC explicitly signaled | Business logic rejection |
| `insufficient funds` | Not enough EGLD/tokens | Sender balance too low |
| `invalid arguments` | Wrong arg count/type | Mismatched function signature |
| `action is not allowed` | Access control | Caller is not owner/admin |
| `contract not found` | Target not deployed | Wrong address or not yet deployed |
| `too much gas` | Gas limit exceeds block limit | Reduce gas limit |

**Common error codes**:
- `10`: Execution Failed
- `6`: User Rejected
- `4`: Invalid Balance

For SC errors, decode the error message from the result data:
- Strip the `@` prefix and error code
- Hex-decode the message portion
- Match against known error strings in the contract

If the error is not immediately clear:

From multiversx/mx-ai-skills, MIT.

More from multiversx/mx-ai-skills