pha-decode

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

Features

• Decode Carbon transaction hex or fetch-and-decode by tx hash
• Decode nested VM transactions and disassemble raw VM scripts
• Decode VM interop calls with ABI-aware argument naming
• Summarize contract deploy / upgrade interops:
  • contract name
  • signer / from
  • script byte length + SHA-256
  • ABI byte length + SHA-256
  • ABI method/event summaries when ABI bytes are present
• Decode classic hex-encoded event payloads
• Decode ROM blobs in:
  • legacy/common VM dictionary format
  • dedicated CROWN format
• Convert Carbon bytes32 addresses to Phantasma addresses and back
• Render stable JSON or human-readable pretty output
• Merge ABI from local files or from RPC contract discovery

Requirements

• Node.js 18+ recommended

Installation

# global install
npm i -g pha-decode

# local development install
npm install
npm run build

# inspect CLI help or version
pha-decode --help
pha-decode --version

Usage

pha-decode <txHex>
pha-decode tx --hex <txHex>
pha-decode tx --hash <txHash> [--rpc <url>]
pha-decode event --hex <eventHex> [--kind <kind>]
pha-decode rom --hex <romHex> [--symbol <symbol>] [--token-id <tokenId>] [--rom-format <mode>]
pha-decode address --bytes32 <hex>
pha-decode address --pha <address>

Common Options

• --format <json|pretty>: output format, default pretty
• --vm-detail <all|calls|ops|none>: VM detail level, default all
• --carbon-detail <all|call|msg|none>: Carbon detail level, default call
• --carbon-addresses <bytes32|pha>: render known Carbon addresses as raw bytes32 or decoded Phantasma addresses, default bytes32
• --protocol <number>: protocol version used for built-in interop ABI selection, default latest known protocol
• --rpc <url>: RPC endpoint for --hash
• --resolve: fetch contract metadata from RPC and merge it into method resolution
• --abi <path>: ABI JSON file or directory to merge into method resolution
• --verbose: enable SDK logging
• --version: print the package version
• --help: print CLI help

Mode-specific flags:

• event mode
  • --kind <eventKind>
• ROM mode
  • --symbol <symbol>
  • --token-id <tokenId>
  • --rom-format <auto|legacy|crown>
• address mode
  • --bytes32 <hex>
  • --pha <address>

Transaction Input Expectations

pha-decode tx --hex accepts either:

• a full Carbon SignedTxMsg hex string
• a raw VM script hex string

It does not accept payload-only RPC fields such as carbonTxData. If you only have a tx hash or an RPC response, use:

pha-decode tx --hash <txHash> --rpc <url>

If the decoded Carbon transaction contains a nested VM transaction, pha-decode extracts it automatically.

Contract Lifecycle Decoding

pha-decode now enriches deploy / upgrade interops in VM output.

For Runtime.DeployContract and Runtime.UpgradeContract, the decoded output includes:

• vm.methodCalls[].summary
  • kind
  • from
  • contractName
  • contractScript
  • optional contractABI
• vm.methodCalls[].args[].details
  • per-script summary:
    • byteLength
    • sha256
    • instructionCount when disassembly succeeds
  • per-ABI summary:
    • byteLength
    • sha256
    • methodCount
    • eventCount
    • decoded method/event descriptors when ABI parsing succeeds

This makes pha-decode useful as a companion to pha-deploy contract deploy --dry-run and pha-deploy contract upgrade --dry-run.

Examples

Decode a tx hash via RPC:

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

Decode a local tx hex or raw VM script:

pha-decode 0xDEADBEEF...

Decode a deploy / upgrade dry-run transaction generated elsewhere:

pha-decode tx --hex <SIGNED_TX_HEX> --vm-detail calls --format pretty

Decode classic event hex:

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

Decode ROM in auto mode:

pha-decode rom \
  --hex 220100F100396A4B73E3ABCD6B9039712944D7DF9E8ABE7211E519A91176E83A28D01B10027965 \
  --symbol CROWN \
  --token-id 80367770225206466995541877216191568684251978941303868068127874072614271067693

Force the legacy/common ROM parser:

pha-decode rom --hex 0x... --rom-format legacy

Convert Carbon bytes32 to a Phantasma address:

pha-decode address --bytes32 f100396a4b73e3abcd6b9039712944d7df9e8abe7211e519a91176e83a28d01b

Convert a Phantasma address back to Carbon bytes32:

pha-decode address --pha P2KKzrLNZK75f4Vtp4wwWocfgoqywBo3zKBWxBXjLgbxXmL

Output Shape

JSON output is stable and machine-friendly:

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

Notes:

• carbon.call is the human-readable Carbon call decode
• carbon.msg is the raw Carbon payload decode
• vm.instructions and vm.methodCalls are controlled by --vm-detail
• --carbon-addresses pha only converts known address-shaped Carbon fields
• event hex decoding applies to classic event payloads only
• ROM auto mode chooses a parser from the available context and falls back with warnings when needed

Dev Shortcuts

This repo ships a justfile with:

• just build
• just test
• just r <args>
• just d <args>

Use just --list to inspect the full local helper set.

Limitations

• --resolve requires --rpc
• if RPC getContracts is incomplete, unresolved methods fall back to raw data
• unknown methods or argument types stay raw; the CLI does not guess
• contract lifecycle summaries depend on the VM interop arguments actually containing script / ABI bytes