# 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 18+ recommended).

## 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 from hex (`--hex`) or from hash (`--hash` + `--rpc`).
* `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         |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://phantasma.gitbook.io/main/developers/tools/pha-decode.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.