@phantom/parsers 0.0.2

package/README.md

@@ -0,0 +1,227 @@
+# @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
+
+```bash
+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:**
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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:
+
+```bash
+# Install dependencies
+yarn install
+
+# Build the package
+yarn build
+
+# Run tests
+yarn test
+```
+
+## License
+
+MIT License - see LICENSE file for details.

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { NetworkId } from '@phantom/client';
+
+interface ParsedTransaction {
+    base64url: string;
+    originalFormat: string;
+}
+interface ParsedMessage {
+    base64url: string;
+}
+/**
+ * Parse a message to base64url format for the client
+ */
+declare function parseMessage(message: string): ParsedMessage;
+/**
+ * Parse a transaction to base64url format based on network type
+ */
+declare function parseTransaction(transaction: any, networkId: NetworkId): Promise<ParsedTransaction>;
+
+export { ParsedMessage, ParsedTransaction, parseMessage, parseTransaction };

package/dist/index.js

@@ -0,0 +1,173 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  parseMessage: () => parseMessage,
+  parseTransaction: () => parseTransaction
+});
+module.exports = __toCommonJS(src_exports);
+var import_base64url = require("@phantom/base64url");
+var import_buffer = require("buffer");
+function parseMessage(message) {
+  return {
+    base64url: (0, import_base64url.stringToBase64url)(message)
+  };
+}
+async function parseTransaction(transaction, networkId) {
+  const networkPrefix = networkId.split(":")[0].toLowerCase();
+  switch (networkPrefix) {
+    case "solana":
+      return parseSolanaTransaction(transaction);
+    case "ethereum":
+    case "eip155":
+    case "polygon":
+    case "optimism":
+    case "arbitrum":
+    case "base":
+      return parseEVMTransaction(transaction);
+    case "sui":
+      return await parseSuiTransaction(transaction);
+    case "bitcoin":
+      return parseBitcoinTransaction(transaction);
+    default:
+      throw new Error(`Unsupported network: ${networkPrefix}`);
+  }
+}
+function parseSolanaTransaction(transaction) {
+  if (transaction?.messageBytes != null) {
+    return {
+      base64url: (0, import_base64url.base64urlEncode)(transaction.messageBytes),
+      originalFormat: "@solana/kit"
+    };
+  }
+  if (typeof transaction?.serialize === "function") {
+    const serialized = transaction.serialize();
+    return {
+      base64url: (0, import_base64url.base64urlEncode)(serialized),
+      originalFormat: "@solana/web3.js"
+    };
+  }
+  if (transaction instanceof Uint8Array) {
+    return {
+      base64url: (0, import_base64url.base64urlEncode)(transaction),
+      originalFormat: "bytes"
+    };
+  }
+  if (typeof transaction === "string") {
+    try {
+      const bytes = import_buffer.Buffer.from(transaction, "base64");
+      return {
+        base64url: (0, import_base64url.base64urlEncode)(new Uint8Array(bytes)),
+        originalFormat: "base64"
+      };
+    } catch {
+      throw new Error("Unsupported Solana transaction format");
+    }
+  }
+  throw new Error("Unsupported Solana transaction format");
+}
+function parseEVMTransaction(transaction) {
+  if (transaction && typeof transaction === "object" && (transaction.to || transaction.data)) {
+    const bytes = new TextEncoder().encode(
+      JSON.stringify(transaction, (_key, value) => typeof value === "bigint" ? value.toString() : value)
+    );
+    return {
+      base64url: (0, import_base64url.base64urlEncode)(bytes),
+      originalFormat: "viem"
+    };
+  }
+  if (transaction?.serialize && typeof transaction.serialize === "function") {
+    const serialized = transaction.serialize();
+    const bytes = new Uint8Array(import_buffer.Buffer.from(serialized.slice(2), "hex"));
+    return {
+      base64url: (0, import_base64url.base64urlEncode)(bytes),
+      originalFormat: "ethers"
+    };
+  }
+  if (transaction instanceof Uint8Array) {
+    return {
+      base64url: (0, import_base64url.base64urlEncode)(transaction),
+      originalFormat: "bytes"
+    };
+  }
+  if (typeof transaction === "string" && transaction.startsWith("0x")) {
+    const bytes = new Uint8Array(import_buffer.Buffer.from(transaction.slice(2), "hex"));
+    return {
+      base64url: (0, import_base64url.base64urlEncode)(bytes),
+      originalFormat: "hex"
+    };
+  }
+  throw new Error("Unsupported EVM transaction format");
+}
+async function parseSuiTransaction(transaction) {
+  if (transaction?.serialize && typeof transaction.serialize === "function") {
+    const serialized = transaction.serialize();
+    return {
+      base64url: (0, import_base64url.base64urlEncode)(serialized),
+      originalFormat: "sui-sdk"
+    };
+  }
+  if (transaction instanceof Uint8Array) {
+    return {
+      base64url: (0, import_base64url.base64urlEncode)(transaction),
+      originalFormat: "bytes"
+    };
+  }
+  if (transaction?.build && typeof transaction.build === "function") {
+    const built = await transaction.build();
+    if (built?.serialize && typeof built.serialize === "function") {
+      const serialized = built.serialize();
+      return {
+        base64url: (0, import_base64url.base64urlEncode)(serialized),
+        originalFormat: "transaction-block"
+      };
+    }
+  }
+  throw new Error("Unsupported Sui transaction format");
+}
+function parseBitcoinTransaction(transaction) {
+  if (transaction?.toBuffer && typeof transaction.toBuffer === "function") {
+    const buffer = transaction.toBuffer();
+    return {
+      base64url: (0, import_base64url.base64urlEncode)(new Uint8Array(buffer)),
+      originalFormat: "bitcoinjs-lib"
+    };
+  }
+  if (transaction instanceof Uint8Array) {
+    return {
+      base64url: (0, import_base64url.base64urlEncode)(transaction),
+      originalFormat: "bytes"
+    };
+  }
+  if (typeof transaction === "string") {
+    const bytes = new Uint8Array(import_buffer.Buffer.from(transaction, "hex"));
+    return {
+      base64url: (0, import_base64url.base64urlEncode)(bytes),
+      originalFormat: "hex"
+    };
+  }
+  throw new Error("Unsupported Bitcoin transaction format");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseMessage,
+  parseTransaction
+});

package/dist/index.mjs

@@ -0,0 +1,147 @@
+// src/index.ts
+import { base64urlEncode, stringToBase64url } from "@phantom/base64url";
+import { Buffer } from "buffer";
+function parseMessage(message) {
+  return {
+    base64url: stringToBase64url(message)
+  };
+}
+async function parseTransaction(transaction, networkId) {
+  const networkPrefix = networkId.split(":")[0].toLowerCase();
+  switch (networkPrefix) {
+    case "solana":
+      return parseSolanaTransaction(transaction);
+    case "ethereum":
+    case "eip155":
+    case "polygon":
+    case "optimism":
+    case "arbitrum":
+    case "base":
+      return parseEVMTransaction(transaction);
+    case "sui":
+      return await parseSuiTransaction(transaction);
+    case "bitcoin":
+      return parseBitcoinTransaction(transaction);
+    default:
+      throw new Error(`Unsupported network: ${networkPrefix}`);
+  }
+}
+function parseSolanaTransaction(transaction) {
+  if (transaction?.messageBytes != null) {
+    return {
+      base64url: base64urlEncode(transaction.messageBytes),
+      originalFormat: "@solana/kit"
+    };
+  }
+  if (typeof transaction?.serialize === "function") {
+    const serialized = transaction.serialize();
+    return {
+      base64url: base64urlEncode(serialized),
+      originalFormat: "@solana/web3.js"
+    };
+  }
+  if (transaction instanceof Uint8Array) {
+    return {
+      base64url: base64urlEncode(transaction),
+      originalFormat: "bytes"
+    };
+  }
+  if (typeof transaction === "string") {
+    try {
+      const bytes = Buffer.from(transaction, "base64");
+      return {
+        base64url: base64urlEncode(new Uint8Array(bytes)),
+        originalFormat: "base64"
+      };
+    } catch {
+      throw new Error("Unsupported Solana transaction format");
+    }
+  }
+  throw new Error("Unsupported Solana transaction format");
+}
+function parseEVMTransaction(transaction) {
+  if (transaction && typeof transaction === "object" && (transaction.to || transaction.data)) {
+    const bytes = new TextEncoder().encode(
+      JSON.stringify(transaction, (_key, value) => typeof value === "bigint" ? value.toString() : value)
+    );
+    return {
+      base64url: base64urlEncode(bytes),
+      originalFormat: "viem"
+    };
+  }
+  if (transaction?.serialize && typeof transaction.serialize === "function") {
+    const serialized = transaction.serialize();
+    const bytes = new Uint8Array(Buffer.from(serialized.slice(2), "hex"));
+    return {
+      base64url: base64urlEncode(bytes),
+      originalFormat: "ethers"
+    };
+  }
+  if (transaction instanceof Uint8Array) {
+    return {
+      base64url: base64urlEncode(transaction),
+      originalFormat: "bytes"
+    };
+  }
+  if (typeof transaction === "string" && transaction.startsWith("0x")) {
+    const bytes = new Uint8Array(Buffer.from(transaction.slice(2), "hex"));
+    return {
+      base64url: base64urlEncode(bytes),
+      originalFormat: "hex"
+    };
+  }
+  throw new Error("Unsupported EVM transaction format");
+}
+async function parseSuiTransaction(transaction) {
+  if (transaction?.serialize && typeof transaction.serialize === "function") {
+    const serialized = transaction.serialize();
+    return {
+      base64url: base64urlEncode(serialized),
+      originalFormat: "sui-sdk"
+    };
+  }
+  if (transaction instanceof Uint8Array) {
+    return {
+      base64url: base64urlEncode(transaction),
+      originalFormat: "bytes"
+    };
+  }
+  if (transaction?.build && typeof transaction.build === "function") {
+    const built = await transaction.build();
+    if (built?.serialize && typeof built.serialize === "function") {
+      const serialized = built.serialize();
+      return {
+        base64url: base64urlEncode(serialized),
+        originalFormat: "transaction-block"
+      };
+    }
+  }
+  throw new Error("Unsupported Sui transaction format");
+}
+function parseBitcoinTransaction(transaction) {
+  if (transaction?.toBuffer && typeof transaction.toBuffer === "function") {
+    const buffer = transaction.toBuffer();
+    return {
+      base64url: base64urlEncode(new Uint8Array(buffer)),
+      originalFormat: "bitcoinjs-lib"
+    };
+  }
+  if (transaction instanceof Uint8Array) {
+    return {
+      base64url: base64urlEncode(transaction),
+      originalFormat: "bytes"
+    };
+  }
+  if (typeof transaction === "string") {
+    const bytes = new Uint8Array(Buffer.from(transaction, "hex"));
+    return {
+      base64url: base64urlEncode(bytes),
+      originalFormat: "hex"
+    };
+  }
+  throw new Error("Unsupported Bitcoin transaction format");
+}
+export {
+  parseMessage,
+  parseTransaction
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@phantom/parsers",
+  "version": "0.0.2",
+  "description": "Transaction and message parsers for Phantom Wallet SDK",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "?pack-release": "When https://github.com/changesets/changesets/issues/432 has a solution we can remove this trick",
+    "pack-release": "rimraf ./_release && yarn pack && mkdir ./_release && tar zxvf ./package.tgz --directory ./_release && rm ./package.tgz",
+    "build": "rimraf ./dist && tsup",
+    "dev": "rimraf ./dist && tsup --watch",
+    "clean": "rm -rf dist",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "lint": "tsc --noEmit && eslint --cache . --ext .ts",
+    "prettier": "prettier --write \"src/**/*.{ts}\""
+  },
+  "dependencies": {
+    "@phantom/base64url": "^0.1.0",
+    "@phantom/client": "^0.1.1",
+    "buffer": "^6.0.3"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.0",
+    "eslint": "8.53.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.5.2",
+    "rimraf": "^6.0.1",
+    "ts-jest": "^29.1.2",
+    "tsup": "^6.7.0",
+    "typescript": "^5.0.4"
+  },
+  "keywords": [
+    "phantom",
+    "parsers",
+    "transaction",
+    "message",
+    "solana",
+    "ethereum",
+    "bitcoin",
+    "sui"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "directory": "_release/package"
+  }
+}