@phantom/parsers

A utility package for parsing and converting various message and transaction formats into base64url format for use with Phantom's API. This package provides a unified interface for handling different blockchain transaction formats and message types across multiple networks.

Installation

npm install @phantom/parsers
# or
yarn add @phantom/parsers

Overview

The parsers package provides two main functions:

• parseMessage - Converts various message formats to base64url
• parseTransaction - Converts various transaction formats to base64url for different blockchain networks

Supported Networks

• Solana (solana:*)
• Ethereum/EVM (ethereum:*, eip155:*, polygon:*, arbitrum:*, optimism:*, base:*, bsc:*, avalanche:*)
• Bitcoin (bitcoin:*)
• Sui (sui:*)

API Reference

parseMessage(message)

Converts various message formats to base64url encoding.

Parameters:

• message (string | Uint8Array | Buffer) - The message to parse

Returns:

• ParsedMessage object with:
  • base64url (string) - Base64url encoded message
  • originalFormat (string) - The detected input format

Example:

import { parseMessage } from "@phantom/parsers";

// Plain text message
const result1 = parseMessage("Hello, Phantom!");
console.log(result1.base64url); // "SGVsbG8sIFBoYW50b20h"
console.log(result1.originalFormat); // "string"

// Uint8Array
const bytes = new TextEncoder().encode("Hello, Phantom!");
const result2 = parseMessage(bytes);
console.log(result2.base64url); // "SGVsbG8sIFBoYW50b20h"
console.log(result2.originalFormat); // "bytes"

parseTransaction(transaction, networkId)

Converts various transaction formats to base64url encoding based on the target network.

Parameters:

• transaction (any) - The transaction object/data to parse
• networkId (NetworkId) - The target network identifier

Returns:

• Promise<ParsedTransaction> object with:
  • base64url (string) - Base64url encoded transaction
  • originalFormat (string) - The detected input format

Supported Transaction Formats

Solana

import { Transaction } from "@solana/web3.js";
import { parseTransaction } from "@phantom/parsers";
import { NetworkId } from "@phantom/client";

// Solana Web3.js Transaction
const transaction = new Transaction().add(/* instructions */);
const result = await parseTransaction(transaction, NetworkId.SOLANA_MAINNET);

// Raw bytes
const rawBytes = new Uint8Array([1, 2, 3, 4]);
const result2 = await parseTransaction(rawBytes, NetworkId.SOLANA_MAINNET);

// Hex string
const result3 = await parseTransaction("0x01020304", NetworkId.SOLANA_MAINNET);

Ethereum/EVM

import { parseTransaction } from "@phantom/parsers";
import { NetworkId } from "@phantom/client";

// Viem/Ethers transaction object
const evmTransaction = {
  to: "0x742d35Cc6634C0532925a3b8D4C8db86fB5C4A7E",
  value: 1000000000000000000n, // 1 ETH in wei
  data: "0x",
  gasLimit: 21000n,
  gasPrice: 20000000000n, // 20 gwei
};

const result = await parseTransaction(evmTransaction, NetworkId.ETHEREUM_MAINNET);

// Raw transaction bytes
const rawTx = new Uint8Array([
  /* transaction bytes */
]);
const result2 = await parseTransaction(rawTx, NetworkId.ETHEREUM_MAINNET);

// Hex-encoded transaction
const result3 = await parseTransaction("0xf86c...", NetworkId.ETHEREUM_MAINNET);

Bitcoin

import { parseTransaction } from "@phantom/parsers";
import { NetworkId } from "@phantom/client";

// Raw transaction bytes
const bitcoinTx = new Uint8Array([
  /* bitcoin transaction bytes */
]);
const result = await parseTransaction(bitcoinTx, NetworkId.BITCOIN_MAINNET);

// Hex-encoded transaction
const result2 = await parseTransaction("0x0100000001...", NetworkId.BITCOIN_MAINNET);

Sui

import { parseTransaction } from "@phantom/parsers";
import { NetworkId } from "@phantom/client";

// Sui transaction bytes
const suiTx = new Uint8Array([
  /* sui transaction bytes */
]);
const result = await parseTransaction(suiTx, NetworkId.SUI_MAINNET);

Format Detection

The parsers automatically detect the input format and handle conversion appropriately:

Message Formats

• String - Plain text messages (UTF-8 encoded)
• Uint8Array/Buffer - Raw byte data
• Base64/Base64url - Already encoded data (re-encoded to base64url)

Transaction Formats

• @solana/web3.js - Solana Web3.js Transaction objects (calls .serialize())
• @solana/kit - Solana Kit transaction objects
• Viem - Ethereum transaction objects with standard fields
• Ethers - Ethereum transaction objects (legacy and modern formats)
• Raw bytes - Uint8Array or Buffer containing transaction data
• Hex strings - "0x"-prefixed hex-encoded transaction data
• Base64/Base64url - Already encoded transaction data

Error Handling

The parsers will throw descriptive errors for:

• Unsupported network identifiers
• Invalid transaction formats for the target network
• Malformed input data
• Encoding/decoding failures

try {
  const result = await parseTransaction(invalidData, "unsupported:network");
} catch (error) {
  console.error("Parsing failed:", error.message);
  // "Unsupported network: unsupported"
}

Integration with Phantom SDKs

This package is used internally by:

• @phantom/browser-sdk - For client-side transaction parsing
• @phantom/server-sdk - For server-side transaction parsing
• @phantom/react-sdk - Through browser-sdk integration

The parsers enable these SDKs to accept native transaction objects from popular libraries like @solana/web3.js, viem, and ethers, providing a seamless developer experience.

Network ID Format

Network IDs follow the format {chain}:{network}:

• Solana: solana:mainnet-beta, solana:devnet, solana:testnet
• Ethereum: ethereum:1 (mainnet), ethereum:5 (goerli)
• EIP-155: eip155:1 (ethereum), eip155:137 (polygon)
• Bitcoin: bitcoin:000000000019d6689c085ae165831e93
• Sui: sui:mainnet, sui:testnet, sui:devnet

Development

This package is part of the Phantom Wallet SDK monorepo. For development:

# Install dependencies
yarn install

# Build the package
yarn build

# Run tests
yarn test

License

MIT License - see LICENSE file for details.