@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
• parseTransactionToBase64Url - 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"

parseTransactionToBase64Url(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 { parseTransactionToBase64Url } from "@phantom/parsers";
import { NetworkId } from "@phantom/client";

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

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

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

Ethereum/EVM

import { parseTransactionToBase64Url } 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 parseTransactionToBase64Url(evmTransaction, NetworkId.ETHEREUM_MAINNET);

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

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

Bitcoin

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

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

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

Sui

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

// Sui transaction bytes
const suiTx = new Uint8Array([
  /* sui transaction bytes */
]);
const result = await parseTransactionToBase64Url(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

Cross-Platform Compatibility

The parsers package is designed to work across different JavaScript environments including browsers, Node.js, and React Native. The package gracefully handles missing dependencies and provides consistent parsing functionality across all supported platforms.

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 parseTransactionToBase64Url(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

# Run integration tests (requires RPC access)
yarn test:integration

Integration Tests

The package includes comprehensive integration tests that create real transactions using actual Solana libraries:

• VersionedTransaction parsing with @solana/web3.js
• Legacy Transaction parsing with @solana/web3.js
• @solana/kit transaction parsing
• Error handling and network resilience

To run integration tests:

1. Copy .env.example to .env
2. Set SOLANA_RPC_URL to your preferred Solana RPC endpoint
3. Run yarn test:integration

Note: Integration tests make real network calls to fetch recent blockhashes but only create local test transactions (no funds required).

License

MIT License - see LICENSE file for details.