@phantom/browser-sdk 0.0.2 → 0.0.4

package/README.md

@@ -1,3 +1,170 @@
 # Phantom Browser SDK
 
-WIP
+The Phantom Browser SDK allows you to interact with the Phantom wallet from your web application. It uses a plugin system to support different blockchains.
+
+## Installation
+
+You can install the SDK using npm or yarn:
+
+**npm:**
+
+```bash
+npm install @phantom/browser-sdk
+```
+
+**yarn:**
+
+```bash
+yarn add @phantom/browser-sdk
+```
+
+## Usage
+
+Here's an example of how to import and use the SDK with the Solana plugin:
+
+```typescript
+import { createPhantom } from "@phantom/browser-sdk";
+import { createSolanaPlugin } from "@phantom/browser-sdk/solana"; // Import the solana plugin
+
+// Create a Phantom instance with the Solana plugin
+const phantom = createPhantom({
+  chainPlugins: [createSolanaPlugin()],
+});
+
+// Now you can use the Solana-specific methods
+async function connectAndSign() {
+  try {
+    // Get the Solana provider (Phantom wallet instance)
+    const provider = phantom.solana.getProvider();
+
+    if (!provider) {
+      console.error("Phantom wallet not found. Please install Phantom.");
+      return;
+    }
+
+    // Attempt to connect to the wallet
+    const connectionResult = await phantom.solana.connect();
+    console.log("Connection Result:", connectionResult.address);
+
+    // Example: Sign in (if supported by the specific provider/plugin)
+    // Construct SolanaSignInData according to your needs
+    const signInData = { domain: window.location.host, statement: "Please sign in to access this dApp." };
+    const signInResult = await phantom.solana.signIn(signInData);
+    console.log("Sign In Result:", signInResult.address);
+
+    // Example: Sign a message
+    const message = new TextEncoder().encode("Hello from Phantom Browser SDK!");
+    const signedMessage = await phantom.solana.signMessage(message, "utf8");
+    console.log("Signed Message:", signedMessage);
+  } catch (error) {
+    console.error("Error interacting with Phantom:", error);
+  }
+}
+
+connectAndSign();
+```
+
+### Available Solana Methods
+
+Once the `phantom.solana` object is initialized, you can access the following methods:
+
+- `getProvider(): PhantomSolanaProvider | null`
+  - Retrieves the Phantom Solana provider instance.
+- `connect(opts?: { onlyIfTrusted?: boolean }): Promise<string>`
+  - Connects to the Phantom wallet. Optionally, `onlyIfTrusted` can be set to true to only connect if the dApp is already trusted.
+- `disconnect(): Promise<void>`
+  - Disconnects from the Phantom wallet.
+- `getAccount(): { status: "connected" | "disconnected"; address: string | null }`
+  - Gets the current connected account state. When account is connected returns a public key, when it's not returns it as null.
+- `signIn(): Promise<SignInResult>`
+  - Initiates a sign-in request to the wallet.
+- `signMessage(message: Uint8Array | string, display?: 'utf8' | 'hex'): Promise<SignedMessage>`
+  - Prompts the user to sign a given message.
+- `signAndSendTransaction(transaction: Transaction): Promise<{ signature: string; address?: string }>`
+  - Prompts the user to sign **and send** a Kit `Transaction` and returns the confirmed signature.
+
+### Event Handling
+
+The SDK also allows you to listen for `connect`, `disconnect`, and `accountChanged` events:
+
+- `addEventListener(event: PhantomEventType, callback: PhantomEventCallback): () => void`
+
+  - Registers a callback that will be invoked when the specified event occurs.
+  - For the `connect` event, the callback receives the public key (as a string) of the connected account.
+  - For the `disconnect` event, the callback receives no arguments.
+  - For the `accountChanged` event, the callback receives the new public key (as a string).
+  - Returns a function that, when called, will unregister the callback.
+  - Multiple callbacks can be registered for the same event.
+
+  **Example:**
+
+  ```typescript
+  const phantom = createPhantom({ chainPlugins: [createSolanaPlugin()] });
+
+  const handleConnect = (address: string) => {
+    console.log(`Wallet connected with public key: ${address}`);
+  };
+
+  const clearConnectListener = phantom.solana.addEventListener("connect", handleConnect);
+
+  const handleAccountChanged = (newAddress: string) => {
+    console.log(`Account changed to: ${newAddress}`);
+  };
+
+  const clearAccountChangedListener = phantom.solana.addEventListener("accountChanged", handleAccountChanged);
+
+  // To stop listening for a specific event:
+  // clearConnectListener();
+  // clearAccountChangedListener();
+  ```
+
+- `removeEventListener(event: PhantomEventType, callback: PhantomEventCallback): void`
+
+  - Unregisters a previously registered callback for the specified event.
+
+  **Example:**
+
+  ```typescript
+  const phantom = createPhantom({ chainPlugins: [createSolanaPlugin()] });
+
+  const handleDisconnect = () => {
+    console.log("Wallet disconnected");
+  };
+
+  phantom.solana.addEventListener("disconnect", handleDisconnect);
+
+  // To stop listening for this specific disconnect event:
+  // phantom.solana.removeEventListener("disconnect", handleDisconnect);
+  ```
+
+### Creating a transaction
+
+Phantom's SDK uses the `@solana/kit` library to create transactions. You can use the `createTransactionMessage` function to create a transaction message.
+
+```typescript
+import {
+  createSolanaRpc,
+  pipe,
+  createTransactionMessage,
+  setTransactionMessageFeePayer,
+  setTransactionMessageLifetimeUsingBlockhash,
+  address,
+  compileTransaction,
+} from "@solana/kit";
+
+// Example: Sign and send a transaction
+
+const rpc = createSolanaRpc("https://my-rpc-url.com"); // Replace with your own RPC URL
+
+const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
+
+const transactionMessage = pipe(
+  createTransactionMessage({ version: 0 }),
+  tx => setTransactionMessageFeePayer(address(userPublicKey as string), tx),
+  tx => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
+);
+
+const transaction = compileTransaction(transactionMessage);
+
+const { signature } = await phantomInstance.solana.signAndSendTransaction(transaction);
+```

package/dist/solana/index.d.ts

@@ -1,7 +1,139 @@
 import { ChainPlugin } from '../index.js';
+import { Transaction as Transaction$1 } from '@solana/kit';
+
+type Transaction = {
+    message: Uint8Array;
+    recentBlockhash: string;
+    feePayer: string;
+    instructions: any[];
+    signers: string[];
+    version: number;
+};
+type VersionedTransaction = {
+    signatures: Uint8Array[];
+    message: {
+        deserialize: (serializedTransaction: Uint8Array) => VersionedTransaction;
+        serialize: (transaction: VersionedTransaction) => Uint8Array;
+    };
+};
+type SendOptions = {
+    skipPreflight?: boolean;
+    preflightCommitment?: string;
+    maxRetries?: number;
+    minContextSlot?: number;
+};
+type PublicKey = {
+    toString: () => string;
+    toBase58: () => string;
+};
+type SolanaSignInData = {
+    domain?: string;
+    address?: string;
+    statement?: string;
+    uri?: string;
+    version?: string;
+    chainId?: string;
+    nonce?: string;
+    issuedAt?: string;
+    expirationTime?: string;
+    notBefore?: string;
+    requestId?: string;
+    resources?: string[];
+};
+type DisplayEncoding = "utf8" | "hex";
+type PhantomEventType = "connect" | "disconnect" | "accountChanged";
+interface PhantomSolanaProvider {
+    isPhantom: boolean;
+    publicKey: PublicKey | null;
+    isConnected: boolean;
+    connect: (opts?: {
+        onlyIfTrusted?: boolean;
+    }) => Promise<{
+        publicKey: PublicKey;
+    }>;
+    disconnect: () => Promise<void>;
+    signMessage: (message: Uint8Array, display?: DisplayEncoding) => Promise<{
+        signature: Uint8Array;
+        publicKey: PublicKey;
+    }>;
+    signIn: (signInData: SolanaSignInData) => Promise<{
+        address: PublicKey;
+        signature: Uint8Array;
+        signedMessage: Uint8Array;
+    }>;
+    signAndSendTransaction: (transaction: Transaction | VersionedTransaction, options?: SendOptions) => Promise<{
+        signature: string;
+        publicKey?: string;
+    }>;
+    signAllTransactions: (transactions: (Transaction | VersionedTransaction)[]) => Promise<(Transaction | VersionedTransaction)[]>;
+    signTransaction: (transaction: Transaction | VersionedTransaction) => Promise<Transaction | VersionedTransaction>;
+    on: (event: "connect" | "disconnect" | "accountChanged", handler: (publicKey?: PublicKey) => void) => void;
+    off: (event: "connect" | "disconnect" | "accountChanged", handler: (publicKey?: PublicKey) => void) => void;
+}
+
+/**
+ * Signs a message using the Phantom provider.
+ * @param message The message to sign (as a Uint8Array).
+ * @param display The display encoding for the message (optional, defaults to utf8).
+ * @returns A promise that resolves with the signature and public key.
+ * @throws Error if Phantom provider is not found or if the operation fails.
+ */
+declare function signMessage(message: Uint8Array, display?: DisplayEncoding): Promise<{
+    signature: Uint8Array;
+    address: string;
+}>;
+
+/**
+ * Signs in with Solana using the Phantom provider.
+ * @param signInData The sign-in data.
+ * @returns A promise that resolves with the address, signature, and signed message.
+ * @throws Error if Phantom provider is not found or if the operation fails.
+ */
+declare function signIn(signInData: SolanaSignInData): Promise<{
+    address: string;
+    signature: Uint8Array;
+    signedMessage: Uint8Array;
+}>;
+
+/**
+ * Signs and sends a transaction using the Phantom provider.
+ * @param transaction The transaction to sign and send.
+ * @returns A promise that resolves with the transaction signature and optionally the public key.
+ * @throws Error if Phantom provider is not found or if the operation fails.
+ */
+declare function signAndSendTransaction(transaction: Transaction$1): Promise<{
+    signature: string;
+    address?: string;
+}>;
+
+declare function connect(): Promise<string | undefined>;
+
+declare function disconnect(): Promise<void>;
+
+type ConnectCallback = (publicKey: string) => void;
+type DisconnectCallback = () => void;
+type AccountChangedCallback = (publicKey: string) => void;
+type PhantomEventCallback = ConnectCallback | DisconnectCallback | AccountChangedCallback;
+
+type GetAccountResult = {
+    status: "connected";
+    address: string;
+} | {
+    status: "disconnected";
+    address: null;
+};
+declare function getAccount(): GetAccountResult;
 
 type Solana = {
-    getProvider: () => NonNullable<unknown> | null;
+    getProvider: () => PhantomSolanaProvider | null;
+    connect: typeof connect;
+    disconnect: typeof disconnect;
+    getAccount: typeof getAccount;
+    signMessage: typeof signMessage;
+    signIn: typeof signIn;
+    signAndSendTransaction: typeof signAndSendTransaction;
+    addEventListener: (event: PhantomEventType, callback: PhantomEventCallback) => () => void;
+    removeEventListener: (event: PhantomEventType, callback: PhantomEventCallback) => void;
 };
 declare function createSolanaPlugin(): ChainPlugin<Solana>;
 
@@ -11,4 +143,4 @@ declare module "../index" {
     }
 }
 
-export { createSolanaPlugin };
+export { PhantomSolanaProvider, SolanaSignInData, createSolanaPlugin };

package/dist/solana/index.js

@@ -29,9 +29,179 @@ function getProvider() {
   return window.phantom?.solana ?? null;
 }
 
+// src/solana/eventListeners.ts
+var eventCallbacks = /* @__PURE__ */ new Map();
+function addEventListener(event, callback) {
+  if (!eventCallbacks.has(event)) {
+    eventCallbacks.set(event, /* @__PURE__ */ new Set());
+  }
+  eventCallbacks.get(event).add(callback);
+  return () => {
+    removeEventListener(event, callback);
+  };
+}
+function removeEventListener(event, callback) {
+  if (eventCallbacks.has(event)) {
+    eventCallbacks.get(event).delete(callback);
+    if (eventCallbacks.get(event).size === 0) {
+      eventCallbacks.delete(event);
+    }
+  }
+}
+function triggerEvent(event, ...args) {
+  if (eventCallbacks.has(event)) {
+    eventCallbacks.get(event).forEach((cb) => {
+      if (event === "connect" && args[0] && typeof args[0] === "string") {
+        cb(args[0]);
+      } else if (event === "disconnect") {
+        cb();
+      } else if (event === "accountChanged" && args[0] && typeof args[0] === "string") {
+        cb(args[0]);
+      }
+    });
+  }
+}
+
+// src/solana/connect.ts
+async function connect() {
+  const provider = getProvider();
+  if (!provider) {
+    throw new Error("Phantom provider not found.");
+  }
+  if (provider.isConnected) {
+    return provider.publicKey?.toString();
+  }
+  try {
+    const eagerConnectResult = await provider.connect({ onlyIfTrusted: true });
+    if (eagerConnectResult.publicKey) {
+      const publicKeyStr = eagerConnectResult.publicKey.toString();
+      triggerEvent("connect", publicKeyStr);
+      return publicKeyStr;
+    }
+  } catch (error) {
+  }
+  try {
+    const connectResult = await provider.connect({ onlyIfTrusted: false });
+    if (connectResult.publicKey) {
+      const publicKeyStr = connectResult.publicKey.toString();
+      triggerEvent("connect", publicKeyStr);
+      return publicKeyStr;
+    }
+  } catch (error) {
+  }
+  throw new Error("Failed to connect to Phantom.");
+}
+
+// src/solana/signMessage.ts
+async function signMessage(message, display) {
+  const provider = getProvider();
+  if (!provider) {
+    throw new Error("Phantom provider not found.");
+  }
+  if (!provider.isConnected) {
+    await connect();
+  }
+  if (!provider.signMessage) {
+    throw new Error("The connected provider does not support signMessage.");
+  }
+  if (!provider.isConnected) {
+    throw new Error("Provider is not connected even after attempting to connect.");
+  }
+  const result = await provider.signMessage(message, display);
+  return {
+    signature: result.signature,
+    address: result.publicKey.toString()
+  };
+}
+
+// src/solana/signIn.ts
+async function signIn(signInData) {
+  const provider = getProvider();
+  if (!provider) {
+    throw new Error("Phantom provider not found.");
+  }
+  if (!provider.signIn) {
+    throw new Error("The connected provider does not support signIn.");
+  }
+  const result = await provider.signIn(signInData);
+  return {
+    address: result.address.toString(),
+    signature: result.signature,
+    signedMessage: result.signedMessage
+  };
+}
+
+// src/solana/utils/transactionToVersionedTransaction.ts
+var import_transactions = require("@solana/transactions");
+function transactionToVersionedTransaction(transaction) {
+  const serialized = (0, import_transactions.getTransactionEncoder)().encode(transaction);
+  const fakeVersioned = {
+    serialize() {
+      return new Uint8Array(serialized);
+    }
+  };
+  return fakeVersioned;
+}
+
+// src/solana/signAndSendTransaction.ts
+async function signAndSendTransaction(transaction) {
+  const provider = getProvider();
+  if (!provider) {
+    throw new Error("Phantom provider not found.");
+  }
+  if (!provider.isConnected) {
+    await connect();
+  }
+  if (!provider.signAndSendTransaction) {
+    throw new Error("The connected provider does not support signAndSendTransaction.");
+  }
+  if (!provider.isConnected) {
+    throw new Error("Provider is not connected even after attempting to connect.");
+  }
+  const versionedTransaction = transactionToVersionedTransaction(transaction);
+  const result = await provider.signAndSendTransaction(versionedTransaction);
+  return {
+    signature: result.signature,
+    address: result.publicKey
+  };
+}
+
+// src/solana/disconnect.ts
+async function disconnect() {
+  const provider = getProvider();
+  if (!provider) {
+    throw new Error("Phantom provider not found.");
+  }
+  await provider.disconnect();
+  triggerEvent("disconnect");
+}
+
+// src/solana/getAccount.ts
+function getAccount() {
+  const provider = getProvider();
+  if (provider && provider.isConnected && provider.publicKey) {
+    return {
+      status: "connected",
+      address: provider.publicKey.toString()
+    };
+  }
+  return {
+    status: "disconnected",
+    address: null
+  };
+}
+
 // src/solana/plugin.ts
 var solana = {
-  getProvider
+  getProvider,
+  connect,
+  disconnect,
+  getAccount,
+  signMessage,
+  signIn,
+  signAndSendTransaction,
+  addEventListener,
+  removeEventListener
 };
 function createSolanaPlugin() {
   return {

package/dist/solana/index.mjs

@@ -3,9 +3,179 @@ function getProvider() {
   return window.phantom?.solana ?? null;
 }
 
+// src/solana/eventListeners.ts
+var eventCallbacks = /* @__PURE__ */ new Map();
+function addEventListener(event, callback) {
+  if (!eventCallbacks.has(event)) {
+    eventCallbacks.set(event, /* @__PURE__ */ new Set());
+  }
+  eventCallbacks.get(event).add(callback);
+  return () => {
+    removeEventListener(event, callback);
+  };
+}
+function removeEventListener(event, callback) {
+  if (eventCallbacks.has(event)) {
+    eventCallbacks.get(event).delete(callback);
+    if (eventCallbacks.get(event).size === 0) {
+      eventCallbacks.delete(event);
+    }
+  }
+}
+function triggerEvent(event, ...args) {
+  if (eventCallbacks.has(event)) {
+    eventCallbacks.get(event).forEach((cb) => {
+      if (event === "connect" && args[0] && typeof args[0] === "string") {
+        cb(args[0]);
+      } else if (event === "disconnect") {
+        cb();
+      } else if (event === "accountChanged" && args[0] && typeof args[0] === "string") {
+        cb(args[0]);
+      }
+    });
+  }
+}
+
+// src/solana/connect.ts
+async function connect() {
+  const provider = getProvider();
+  if (!provider) {
+    throw new Error("Phantom provider not found.");
+  }
+  if (provider.isConnected) {
+    return provider.publicKey?.toString();
+  }
+  try {
+    const eagerConnectResult = await provider.connect({ onlyIfTrusted: true });
+    if (eagerConnectResult.publicKey) {
+      const publicKeyStr = eagerConnectResult.publicKey.toString();
+      triggerEvent("connect", publicKeyStr);
+      return publicKeyStr;
+    }
+  } catch (error) {
+  }
+  try {
+    const connectResult = await provider.connect({ onlyIfTrusted: false });
+    if (connectResult.publicKey) {
+      const publicKeyStr = connectResult.publicKey.toString();
+      triggerEvent("connect", publicKeyStr);
+      return publicKeyStr;
+    }
+  } catch (error) {
+  }
+  throw new Error("Failed to connect to Phantom.");
+}
+
+// src/solana/signMessage.ts
+async function signMessage(message, display) {
+  const provider = getProvider();
+  if (!provider) {
+    throw new Error("Phantom provider not found.");
+  }
+  if (!provider.isConnected) {
+    await connect();
+  }
+  if (!provider.signMessage) {
+    throw new Error("The connected provider does not support signMessage.");
+  }
+  if (!provider.isConnected) {
+    throw new Error("Provider is not connected even after attempting to connect.");
+  }
+  const result = await provider.signMessage(message, display);
+  return {
+    signature: result.signature,
+    address: result.publicKey.toString()
+  };
+}
+
+// src/solana/signIn.ts
+async function signIn(signInData) {
+  const provider = getProvider();
+  if (!provider) {
+    throw new Error("Phantom provider not found.");
+  }
+  if (!provider.signIn) {
+    throw new Error("The connected provider does not support signIn.");
+  }
+  const result = await provider.signIn(signInData);
+  return {
+    address: result.address.toString(),
+    signature: result.signature,
+    signedMessage: result.signedMessage
+  };
+}
+
+// src/solana/utils/transactionToVersionedTransaction.ts
+import { getTransactionEncoder } from "@solana/transactions";
+function transactionToVersionedTransaction(transaction) {
+  const serialized = getTransactionEncoder().encode(transaction);
+  const fakeVersioned = {
+    serialize() {
+      return new Uint8Array(serialized);
+    }
+  };
+  return fakeVersioned;
+}
+
+// src/solana/signAndSendTransaction.ts
+async function signAndSendTransaction(transaction) {
+  const provider = getProvider();
+  if (!provider) {
+    throw new Error("Phantom provider not found.");
+  }
+  if (!provider.isConnected) {
+    await connect();
+  }
+  if (!provider.signAndSendTransaction) {
+    throw new Error("The connected provider does not support signAndSendTransaction.");
+  }
+  if (!provider.isConnected) {
+    throw new Error("Provider is not connected even after attempting to connect.");
+  }
+  const versionedTransaction = transactionToVersionedTransaction(transaction);
+  const result = await provider.signAndSendTransaction(versionedTransaction);
+  return {
+    signature: result.signature,
+    address: result.publicKey
+  };
+}
+
+// src/solana/disconnect.ts
+async function disconnect() {
+  const provider = getProvider();
+  if (!provider) {
+    throw new Error("Phantom provider not found.");
+  }
+  await provider.disconnect();
+  triggerEvent("disconnect");
+}
+
+// src/solana/getAccount.ts
+function getAccount() {
+  const provider = getProvider();
+  if (provider && provider.isConnected && provider.publicKey) {
+    return {
+      status: "connected",
+      address: provider.publicKey.toString()
+    };
+  }
+  return {
+    status: "disconnected",
+    address: null
+  };
+}
+
 // src/solana/plugin.ts
 var solana = {
-  getProvider
+  getProvider,
+  connect,
+  disconnect,
+  getAccount,
+  signMessage,
+  signIn,
+  signAndSendTransaction,
+  addEventListener,
+  removeEventListener
 };
 function createSolanaPlugin() {
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phantom/browser-sdk",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -22,13 +22,20 @@
   "license": "MIT",
   "scripts": {
     "build": "rm -rf dist && tsup src/index.ts src/solana/index.ts --format cjs,esm --dts",
+    "build:watch": "rm -rf dist && tsup src/index.ts src/solana/index.ts --format cjs,esm --dts --watch",
     "dev": "rm -rf dist && tsup src/index.ts src/solana/index.ts --format cjs,esm --dts --watch",
     "lint": "tsc --noEmit && eslint --cache . --ext .ts,.tsx",
     "test": "jest"
   },
   "devDependencies": {
+    "@solana/web3.js": "^1.98.2",
     "eslint": "8.53.0",
     "tsup": "^6.7.0",
     "typescript": "^5.0.4"
+  },
+  "dependencies": {
+    "@solana/compat": "2.1.1",
+    "@solana/kit": "^2.1.1",
+    "@solana/transactions": "^2.1.1"
   }
 }