> For the complete documentation index, see [llms.txt](https://phantasma.gitbook.io/main/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://phantasma.gitbook.io/main/developers/tools/pha-decode.md).

# pha-decode

CLI tool for decoding Phantasma Carbon + VM transactions, contract lifecycle scripts, legacy event hex, ROM blobs, and address conversions.

## What it can decode

* Carbon transaction hex or a transaction fetched by hash.
* Carbon `Phantasma` / `Phantasma_Raw` wrappers reconstructed into a VM view.
* VM transaction containers and raw VM scripts, including disassembly and method calls.
* Deploy / upgrade interops with contract name, signer, script hash, ABI hash, and ABI method/event summaries when ABI bytes are present.
* Legacy event hex payloads.
* ROM blobs in auto, legacy/common, or `CROWN` mode.
* Carbon `bytes32` addresses to Phantasma addresses and back.
* Phantasma address derivation from WIF, a 32-byte private key, modern BIP44 seed phrases, or legacy Poltergeist seed phrases.
* JSON or pretty text output.
* Optional ABI resolution from local files or RPC.

## Requirements

* Node.js with ESM support (Node `>=22`).

## Installation

```bash
# install globally
npm i -g pha-decode

# or run once via npx
npx pha-decode --help
npx pha-decode --version

# local dev install
npm install
npm run build
```

## Quick start

Decode a local transaction hex (shorthand):

```bash
pha-decode 0xDEADBEEF...
```

Decode a transaction hash from RPC:

```bash
pha-decode tx --hash 155422A6882C3342933521DDC1A335292BF6448DBD489ED0BE21CFC74AFBA52A \
  --rpc https://pharpc1.phantasma.info/rpc \
  --format json \
  --vm-detail calls \
  --carbon-detail call
```

Decode legacy event hex:

```bash
pha-decode event --hex 0xAABBCC... --kind TokenMint
```

Decode ROM:

```bash
pha-decode rom --hex 0x... --symbol CROWN --token-id 80367770225206466995541877216191568684251978941303868068127874072614271067693
```

Convert addresses:

```bash
pha-decode address --bytes32 f100396a4b73e3abcd6b9039712944d7df9e8abe7211e519a91176e83a28d01b
pha-decode address --pha P2KKzrLNZK75f4Vtp4wwWocfgoqywBo3zKBWxBXjLgbxXmL
```

## Commands and inputs

`pha-decode` supports four commands:

* `tx` (default): decode a transaction. Provide it as raw hex (`--hex`), fetch it by hash (`--hash` with `--rpc`), pass an RPC transaction JSON (`--rpc-json <path|->`), or decode a Carbon transaction body (`--carbon-tx-data`, with optional `--carbon-tx-type`). Optional context: `--payload`, `--expiration`, `--gas-payer`, `--signature-count`.
* `event`: decode legacy event data from hex (`--hex`) with an optional event kind (`--kind`).
* `rom`: decode ROM hex (`--hex`) with optional `--symbol`, `--token-id`, and `--rom-format`.
* `address`: convert or derive addresses from `--bytes32`, `--pha`, `--wif`, `--private-key`, `--mnemonic`, or `--mnemonic-legacy`.

Input rules:

* Hex strings may include `0x` prefix and must have even length.
* `--hash` requires `--rpc`.
* `event` mode requires `--hex`.
* `rom` mode requires `--hex`.
* `address` mode requires exactly one address input selector. Use `--stdin` with the selector to read secret input from standard input.

## Output formats

`--format` controls output:

* `pretty` (default): human readable sections.
* `json`: machine friendly output.

JSON output structure (example):

```json
{
  "source": "tx-hash",
  "input": "155422A6...",
  "rpc": { "url": "https://...", "method": "getTransaction" },
  "carbon": { "...": "..." },
  "vm": { "...": "..." },
  "event": { "...": "..." },
  "rom": { "...": "..." },
  "address": { "...": "..." },
  "warnings": [],
  "errors": []
}
```

## Option reference

General:

* `--format <json|pretty>` Output format (default: `pretty`).
* `--rpc <url>` RPC endpoint for `--hash`.
* `--resolve` Fetch contract ABIs from RPC and merge into the method table.
* `--abi <path>` ABI JSON file or directory (merged with built-ins).
* `--protocol <number>` Protocol version used for ABI selection (default: latest known).
* `--protocol-version <number>` Alias for `--protocol`.
* `--verbose` Enable SDK logging.
* `--help` Show help.
* `--version` Show the package version.

VM output detail:

* `--vm-detail <all|calls|ops|none>` Control VM output (default: `all`).
  * Accepted aliases: `both` -> `all`, `methods` -> `calls`, `opcodes` -> `ops`, `off` -> `none`.

Carbon output detail:

* `--carbon-detail <all|call|msg|none>` Control Carbon output (default: `call`).
* `--carbon-addresses <bytes32|pha>` Render known Carbon address fields as raw `bytes32` or decoded Phantasma addresses (default: `bytes32`).

Event decoding:

* `--kind <eventKind>` Event kind hint for legacy event hex. Accepts numeric id or name.

ROM decoding:

* `--symbol <symbol>` ROM symbol hint, for example `CROWN`.
* `--token-id <tokenId>` ROM token id hint.
* `--rom-format <auto|legacy|crown>` ROM parser mode (default: `auto`).

Address decoding:

* `--bytes32 <hex>` Carbon bytes32 address input.
* `--pha <address>` Phantasma address input.
* `--wif <wif>` WIF private-key input; redacted in output.
* `--private-key <hex>` 32-byte private-key input; redacted in output.
* `--mnemonic <words>` / `--seed-phrase <words>` Modern BIP44 seed phrase input; redacted in output.
* `--mnemonic-legacy <words>` / `--legacy-mnemonic <words>` Legacy Poltergeist seed phrase input; redacted in output.
* `--legacy-password <password>` Optional legacy seed password; redacted in output.
* `--stdin` Read the selected address input from standard input.
* `--index <n>` / `--derivation-index <n>` Address derivation index for modern mnemonic input (default: `0`).

### Mode rules

When `event` is selected:

* `--abi`, `--resolve`, `--vm-detail`, and `--carbon-detail` are ignored.
* If `--kind` is omitted or unknown, the tool returns raw hex with a warning.

When `rom` is selected:

* `--abi`, `--resolve`, `--vm-detail`, `--carbon-detail`, and `--rpc` are ignored.
* Auto mode chooses a parser from the available context and falls back with warnings when needed.

When `address` is selected:

* `--abi`, `--resolve`, `--vm-detail`, `--carbon-detail`, and `--rpc` are ignored.
* Secret inputs are redacted from CLI output. Prefer `--stdin` for scripts and shells where history matters.

## ABI resolution

The decoder starts with built-in ABI definitions. You can add more:

* `--abi <path>` loads a JSON file or a directory of JSON files and merges into the method table.
* `--resolve` uses the RPC `getContracts` output and merges contract methods.

If the RPC returns no contracts or a method is unknown, the decoder keeps raw hex values and adds warnings instead of guessing.

## Event kinds (legacy)

`--kind` accepts either the numeric id or the name (case-insensitive, whitespace ignored).

| Id | Name               |
| -- | ------------------ |
| 0  | Unknown            |
| 1  | ChainCreate        |
| 2  | TokenCreate        |
| 3  | TokenSend          |
| 4  | TokenReceive       |
| 5  | TokenMint          |
| 6  | TokenBurn          |
| 7  | TokenStake         |
| 8  | TokenClaim         |
| 9  | AddressRegister    |
| 10 | AddressLink        |
| 11 | AddressUnlink      |
| 12 | OrganizationCreate |
| 13 | OrganizationAdd    |
| 14 | OrganizationRemove |
| 15 | GasEscrow          |
| 16 | GasPayment         |
| 17 | AddressUnregister  |
| 18 | OrderCreated       |
| 19 | OrderCancelled     |
| 20 | OrderFilled        |
| 21 | OrderClosed        |
| 22 | FeedCreate         |
| 23 | FeedUpdate         |
| 24 | FileCreate         |
| 25 | FileDelete         |
| 26 | ValidatorPropose   |
| 27 | ValidatorElect     |
| 28 | ValidatorRemove    |
| 29 | ValidatorSwitch    |
| 30 | PackedNFT          |
| 31 | ValueCreate        |
| 32 | ValueUpdate        |
| 33 | PollCreated        |
| 34 | PollClosed         |
| 35 | PollVote           |
| 36 | ChannelCreate      |
| 37 | ChannelRefill      |
| 38 | ChannelSettle      |
| 39 | LeaderboardCreate  |
| 40 | LeaderboardInsert  |
| 41 | LeaderboardReset   |
| 42 | PlatformCreate     |
| 43 | ChainSwap          |
| 44 | ContractRegister   |
| 45 | ContractDeploy     |
| 46 | AddressMigration   |
| 47 | ContractUpgrade    |
| 48 | Log                |
| 49 | Inflation          |
| 50 | OwnerAdded         |
| 51 | OwnerRemoved       |
| 52 | DomainCreate       |
| 53 | DomainDelete       |
| 54 | TaskStart          |
| 55 | TaskStop           |
| 56 | CrownRewards       |
| 57 | Infusion           |
| 58 | Crowdsale          |
| 59 | OrderBid           |
| 60 | ContractKill       |
| 61 | OrganizationKill   |
| 62 | MasterClaim        |
| 63 | ExecutionFailure   |
| 64 | Custom             |
| 65 | Custom\_V2         |