@phantom/server-sdk 0.0.2 → 0.0.4

package/README.md

@@ -1,208 +1,70 @@
-# Server SDK
+# Phantom Server SDK
 
-This package provides integration with @phantom/openapi-wallet-service for secure wallet management and transaction signing.
+The Phantom Server SDK provides a secure and straightforward way to create and manage wallets, sign transactions, and interact with multiple blockchains from your backend services.
 
-## Installation
-
-```bash
-npm install @phantom/server-sdk
-```
-
-## Configuration
+## 📖 Documentation
 
-The SDK requires the following configuration:
+Visit **[docs.phantom.com/server-sdk](https://docs.phantom.com/server-sdk)** for comprehensive documentation including:
 
-- `apiPrivateKey`: Your signing key for authentication (base58 encoded)
-- `organizationId`: Your organization ID from Phantom
-- `apiBaseUrl`: The wallet API endpoint URL
+- Getting Started Guide
+- Creating and Managing Wallets
+- Signing Transactions
+- Signing Messages
+- Complete API Reference
+- Integration Examples
+- Best Practices
+- Security Considerations
 
-```typescript
-import { ServerSDK } from '@phantom/server-sdk';
+## Installation
 
-const sdk = new ServerSDK({
-  apiPrivateKey: 'your-signing-key-base58',
-  organizationId: 'your-org-id',
-  apiBaseUrl: 'https://api.phantom.app/v1'
-});
+```bash
+npm install @phantom/server-sdk
 ```
 
-## Network Identifiers
-
-The SDK provides user-friendly enums for CAIP-2 network identifiers:
-
-```typescript
-import { NetworkId } from '@phantom/server-sdk';
-
-// Use the NetworkId enum for easy access to CAIP-2 identifiers
-const solanaMainnet = NetworkId.SOLANA_MAINNET; // 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'
-const ethMainnet = NetworkId.ETHEREUM_MAINNET;  // 'eip155:1'
-const polygonMainnet = NetworkId.POLYGON_MAINNET; // 'eip155:137'
-
-// Example usage with SDK methods
-const result = await sdk.signAndSendTransaction(
-  walletId,
-  transaction,
-  NetworkId.SOLANA_MAINNET  // Instead of hardcoding 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'
-);
-
-// Sign a message on Ethereum
-const signature = await sdk.signMessage(
-  walletId,
-  'Hello World',
-  NetworkId.ETHEREUM_MAINNET
-);
-
-
+```bash
+yarn add @phantom/server-sdk
 ```
 
-### Available Networks
-
-| Network | Enum Value | CAIP-2 ID |
-|---------|-----------|-----------|
-| **Solana** | | |
-| Mainnet | `NetworkId.SOLANA_MAINNET` | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` |
-| Devnet | `NetworkId.SOLANA_DEVNET` | `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` |
-| Testnet | `NetworkId.SOLANA_TESTNET` | `solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z` |
-| **Ethereum** | | |
-| Mainnet | `NetworkId.ETHEREUM_MAINNET` | `eip155:1` |
-| Goerli | `NetworkId.ETHEREUM_GOERLI` | `eip155:5` |
-| Sepolia | `NetworkId.ETHEREUM_SEPOLIA` | `eip155:11155111` |
-| **Polygon** | | |
-| Mainnet | `NetworkId.POLYGON_MAINNET` | `eip155:137` |
-| Mumbai | `NetworkId.POLYGON_MUMBAI` | `eip155:80001` |
-| **Arbitrum** | | |
-| One | `NetworkId.ARBITRUM_ONE` | `eip155:42161` |
-| Goerli | `NetworkId.ARBITRUM_GOERLI` | `eip155:421613` |
-| **Base** | | |
-| Mainnet | `NetworkId.BASE_MAINNET` | `eip155:8453` |
-| Sepolia | `NetworkId.BASE_SEPOLIA` | `eip155:84532` |
-
-## CAIP-2 Network Identifiers
-
-This SDK uses the CAIP-2 (Chain Agnostic Improvement Proposal 2) standard for network identifiers. CAIP-2 provides a standardized way to identify blockchain networks across different ecosystems.
-
-### Format
-CAIP-2 identifiers follow the format: `namespace:reference`
-
-### Common Network IDs
-- **Solana Mainnet**: `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`
-- **Solana Devnet**: `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`
-- **Ethereum Mainnet**: `eip155:1`
-- **Polygon Mainnet**: `eip155:137`
-- **Arbitrum One**: `eip155:42161`
-- **Base Mainnet**: `eip155:8453`
-
-## Methods
-
-### createWallet(walletName?: string)
-Creates a new wallet with an optional name. If no name is provided, a default name with timestamp is used.
-After creation, it retrieves the public key by signing an empty payload.
-
-```typescript
-const wallet = await sdk.createWallet('My Main Wallet');
-// Returns: { 
-//   walletId: 'wallet-uuid',
-//   addresses: [{ addressType: 'Solana', address: 'public-key' }]
-// }
+```bash
+pnpm add @phantom/server-sdk
 ```
 
-### signAndSendTransaction(walletId: string, transaction: Uint8Array, networkId: string)
-Signs a transaction using the wallet service. The transaction should be provided as a Uint8Array and will be encoded as base64 before sending to the KMS.
-
-The SDK automatically derives the submission configuration from the CAIP-2 network ID. If the network supports transaction submission, Phantom will submit the transaction to the blockchain after signing.
-
-**Note:** This method returns only the signed transaction data. To get the transaction hash/signature, you need to extract it from the signed transaction.
+## Quick Start
 
 ```typescript
-import { NetworkId } from '@phantom/server-sdk';
+import { ServerSDK, NetworkId } from '@phantom/server-sdk';
 
-const transactionBuffer = new Uint8Array([...]); // Your serialized transaction
-const result = await sdk.signAndSendTransaction(
-  'wallet-id',
-  transactionBuffer,
-  NetworkId.SOLANA_MAINNET // Using enum - submission config automatically derived
-);
-
-// Returns: { 
-//   rawTransaction: 'base64-signed-transaction'
-// }
-
-// Extract the transaction signature (hash)
-// Note: requires 'import bs58 from "bs58"'
-const signedTx = Transaction.from(Buffer.from(result.rawTransaction, 'base64'));
-const signature = signedTx.signature 
-  ? bs58.encode(signedTx.signature)
-  : bs58.encode(signedTx.signatures[0].signature);
-```
+// Initialize the SDK
+const sdk = new ServerSDK({
+  organizationId: process.env.PHANTOM_ORGANIZATION_ID!,
+  apiPrivateKey: process.env.PHANTOM_PRIVATE_KEY!,
+  apiBaseUrl: process.env.PHANTOM_API_URL!
+});
 
-### signMessage(walletId: string, message: string, networkId: string)
-Signs a message with the specified wallet using the signRawPayload method.
+// Create a wallet
+const wallet = await sdk.createWallet('My First Wallet');
+console.log('Wallet ID:', wallet.walletId);
+console.log('Addresses:', wallet.addresses);
 
-```typescript
+// Sign a message
 const signature = await sdk.signMessage(
-  'wallet-id', 
-  'Hello World', 
-  NetworkId.SOLANA_MAINNET // Using enum for CAIP-2 network ID
+  wallet.walletId,
+  'Hello, Phantom!',
+  NetworkId.SOLANA_MAINNET
 );
-// Returns: base64 encoded signature
-```
-
-## CAIP-2 Utility Functions
-
-The SDK exports several utility functions for working with CAIP-2 network identifiers:
-
-```typescript
-import {
-  deriveSubmissionConfig,
-  supportsTransactionSubmission,
-  getNetworkDescription,
-  getSupportedNetworkIds,
-  getNetworkIdsByChain
-} from '@phantom/server-sdk';
-
-// Check if a network supports transaction submission
-if (supportsTransactionSubmission('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp')) {
-  // Network supports automatic transaction submission
-}
-
-// Get human-readable network description
-const description = getNetworkDescription('eip155:137'); // "Polygon Mainnet"
-
-// List all supported networks
-const allNetworks = getSupportedNetworkIds();
-
-// Get networks for a specific chain
-const solanaNetworks = getNetworkIdsByChain('solana');
-// ['solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1', ...]
+console.log('Signature:', signature);
 ```
 
-## Implementation Details
-
-This SDK uses the @phantom/openapi-wallet-service package which provides:
-- `createWallet` - Creates a new wallet and retrieves its public key via signRawPayload
-- `signTransaction` - Signs transactions with the wallet's private key
-- `signRawPayload` - Signs raw payloads/messages and returns signature with public key
-
-The SDK handles:
-- Network-specific algorithms and curves automatically
-- Standard derivation paths for each blockchain
-- Base64 encoding for transaction data
-- Authentication via Ed25519 signatures
-- CAIP-2 network ID parsing and submission config derivation
-
-## Authentication
+For complete documentation and examples, visit **[docs.phantom.com/server-sdk](https://docs.phantom.com/server-sdk)**.
 
-The SDK authenticates requests using Ed25519 signatures:
-- Each request is signed with your organization's private key
-- The signature, public key, and timestamp are added as headers
-- This ensures secure communication with the Phantom wallet service
+## Resources
 
+- [Documentation](https://docs.phantom.com/server-sdk)
+- [Example Code](https://github.com/phantom/wallet-sdk/tree/main/examples/server-sdk-examples)
+- [Integration Guide](https://docs.phantom.com/server-sdk/integration-guide)
+- [API Reference](https://docs.phantom.com/server-sdk/api-reference)
+- [Changelog](./CHANGELOG.md)
 
-## Notes
+## License
 
-- The wallet ID is a UUID assigned by the service when creating the wallet
-- Public keys are retrieved using the signRawPayload method with an empty payload
-- Transaction hashes are not returned by the signing service - they're generated after blockchain submission
-- The service returns the public key that signed the transaction in the signature field
-- Default wallet names include a timestamp to ensure uniqueness
-- Message signing supports both Solana (Ed25519) and Ethereum (Secp256k1) networks
+This SDK is distributed under the MIT License. See the [LICENSE](../../LICENSE) file for details.

package/dist/auth.js

@@ -16,7 +16,7 @@ function createAuthenticatedAxiosInstance(signingKeypair) {
         const requestBody = typeof config.data === "string" ? config.data : JSON.stringify(config.data);
         const dataUtf8 = Buffer.from(requestBody, "utf8");
         const signature = tweetnacl_1.default.sign.detached(dataUtf8, signingKeypair.secretKey);
-        config.headers["X-Phantom-Sig"] = Buffer.from(signature).toString("base64");
+        config.headers["X-Phantom-Sig"] = Buffer.from(signature).toString("base64url");
         return config;
     });
     return instance;

package/dist/constants.d.ts

@@ -1,10 +1,11 @@
 import { DerivationInfoCurveEnum, DerivationInfoAddressFormatEnum, Algorithm } from '@phantom/openapi-wallet-service';
+import { NetworkId } from './caip2-mappings';
 /**
  * Default derivation paths for different blockchain networks
  */
 export declare enum DerivationPath {
     Solana = "m/44'/501'/0'/0'",
-    Ethereum = "m/44'/60'/0'/0",
+    Ethereum = "m/44'/60'/0'/0/0",
     Bitcoin = "m/84'/0'/0'/0",
     Sui = "m/44'/784'/0'/0'/0'"
 }
@@ -24,4 +25,4 @@ export interface NetworkConfig {
 /**
  * Get complete network configuration
  */
-export declare function getNetworkConfig(networkId: string): NetworkConfig;
+export declare function getNetworkConfig(networkId: NetworkId): NetworkConfig | null;

package/dist/constants.js

@@ -12,7 +12,7 @@ var DerivationPath;
     // Solana - BIP44 standard for Solana (coin type 501)
     DerivationPath["Solana"] = "m/44'/501'/0'/0'";
     // Ethereum - BIP44 standard for Ethereum and all EVM-compatible chains (coin type 60)
-    DerivationPath["Ethereum"] = "m/44'/60'/0'/0";
+    DerivationPath["Ethereum"] = "m/44'/60'/0'/0/0";
     // Bitcoin - BIP44 standard for Bitcoin (coin type 0)
     DerivationPath["Bitcoin"] = "m/84'/0'/0'/0";
     // Sui - BIP44 standard for Sui (coin type 784)
@@ -68,7 +68,7 @@ function getNetworkConfig(networkId) {
                 algorithm: openapi_wallet_service_1.Algorithm.secp256k1,
                 addressFormat: openapi_wallet_service_1.DerivationInfoAddressFormatEnum.bitcoinSegwit // Bitcoin uses a different format, but for SDK consistency we use Ethereum format
             };
-        default:
+        case 'eip155': // EVM chains use eip155 prefix
             // All EVM-compatible chains (Ethereum, Polygon, BSC, Arbitrum, etc.)
             return {
                 derivationPath: DerivationPath.Ethereum,
@@ -76,5 +76,7 @@ function getNetworkConfig(networkId) {
                 algorithm: openapi_wallet_service_1.Algorithm.secp256k1,
                 addressFormat: openapi_wallet_service_1.DerivationInfoAddressFormatEnum.ethereum // EVM chains use Ethereum address format
             };
+        default:
+            return null;
     }
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { ServerSDKConfig, CreateWalletResult, Transaction, SignedTransaction } from "./types";
+import { ServerSDKConfig, CreateWalletResult, Transaction, SignedTransaction, GetWalletsResult } from "./types";
+import { NetworkId } from "./caip2-mappings";
 export interface SubmissionConfig {
     chain: string;
     network: string;
@@ -10,11 +11,12 @@ export declare class ServerSDK {
     private signingKeypair;
     constructor(config: ServerSDKConfig);
     createWallet(walletName?: string): Promise<CreateWalletResult>;
-    signAndSendTransaction(walletId: string, transaction: Transaction, networkId: string): Promise<SignedTransaction>;
+    signAndSendTransaction(walletId: string, transaction: Transaction, networkId: NetworkId): Promise<SignedTransaction>;
     getWalletAddresses(walletId: string, derivationPaths?: string[]): Promise<{
         addressType: string;
         address: string;
     }[]>;
-    signMessage(walletId: string, message: string, networkId: string): Promise<string>;
+    signMessage(walletId: string, message: string, networkId: NetworkId): Promise<string>;
+    getWallets(limit?: number, offset?: number): Promise<GetWalletsResult>;
 }
 export * from "./types";

package/dist/index.js

@@ -97,47 +97,43 @@ class ServerSDK {
     async signAndSendTransaction(walletId, transaction, networkId) {
         try {
             // Encode the Uint8Array as a base64 string
-            const encodedTransaction = Buffer.from(transaction).toString('base64');
+            const encodedTransaction = Buffer.from(transaction).toString('base64url');
             const submissionConfig = (0, caip2_mappings_1.deriveSubmissionConfig)(networkId);
             // If we don't have a submission config, the transaction will only be signed, not submitted
             if (!submissionConfig) {
                 console.warn(`No submission config available for network ${networkId}. Transaction will be signed but not submitted.`);
             }
-            // For Solana transactions
-            if (networkId.startsWith("solana:")) {
-                // Get network configuration
-                const networkConfig = (0, constants_1.getNetworkConfig)(networkId);
-                const derivationInfo = {
-                    derivationPath: networkConfig.derivationPath,
-                    curve: networkConfig.curve,
-                    addressFormat: networkConfig.addressFormat,
-                };
-                // Sign transaction request - only include submissionConfig if available
-                const signRequest = {
-                    organizationId: this.config.organizationId,
-                    walletId: walletId,
-                    transaction: encodedTransaction,
-                    derivationInfo: derivationInfo,
-                };
-                // Add submission config if available
-                if (submissionConfig) {
-                    signRequest.submissionConfig = submissionConfig;
-                }
-                const request = {
-                    method: openapi_wallet_service_1.SignTransactionMethodEnum.signTransaction,
-                    params: signRequest,
-                    timestampMs: Date.now(),
-                };
-                const response = await this.kmsApi.postKmsRpc(request);
-                const result = response.data.result;
-                return {
-                    rawTransaction: result.transaction, // Base64 encoded signed transaction
-                };
+            // Get network configuration
+            const networkConfig = (0, constants_1.getNetworkConfig)(networkId);
+            if (!networkConfig) {
+                throw new Error(`Unsupported network ID: ${networkId}`);
             }
-            else {
-                // For EVM chains (future implementation)
-                throw new Error("EVM transaction signing not yet implemented");
+            const derivationInfo = {
+                derivationPath: networkConfig.derivationPath,
+                curve: networkConfig.curve,
+                addressFormat: networkConfig.addressFormat,
+            };
+            // Sign transaction request - only include submissionConfig if available
+            const signRequest = {
+                organizationId: this.config.organizationId,
+                walletId: walletId,
+                transaction: encodedTransaction,
+                derivationInfo: derivationInfo,
+            };
+            // Add submission config if available
+            if (submissionConfig) {
+                signRequest.submissionConfig = submissionConfig;
             }
+            const request = {
+                method: openapi_wallet_service_1.SignTransactionMethodEnum.signTransaction,
+                params: signRequest,
+                timestampMs: Date.now(),
+            };
+            const response = await this.kmsApi.postKmsRpc(request);
+            const result = response.data.result;
+            return {
+                rawTransaction: result.transaction, // Base64 encoded signed transaction
+            };
         }
         catch (error) {
             console.error("Failed to sign and send transaction:", error.response?.data || error.message);
@@ -175,19 +171,21 @@ class ServerSDK {
     }
     async signMessage(walletId, message, networkId) {
         try {
-            // Convert message to byte array
-            const messageBytes = Array.from(Buffer.from(message, "utf8"));
             // Get network configuration
             const networkConfig = (0, constants_1.getNetworkConfig)(networkId);
+            if (!networkConfig) {
+                throw new Error(`Unsupported network ID: ${networkId}`);
+            }
             const derivationInfo = {
                 derivationPath: networkConfig.derivationPath,
                 curve: networkConfig.curve,
                 addressFormat: networkConfig.addressFormat,
             };
+            const base64StringMessage = Buffer.from(message, "utf8").toString("base64url");
             const signRequest = {
                 organizationId: this.config.organizationId,
                 walletId: walletId,
-                payload: messageBytes,
+                payload: base64StringMessage,
                 algorithm: networkConfig.algorithm,
                 derivationInfo: derivationInfo,
             };
@@ -206,6 +204,36 @@ class ServerSDK {
             throw new Error(`Failed to sign message: ${error.response?.data?.message || error.message}`);
         }
     }
+    async getWallets(limit, offset) {
+        try {
+            const request = {
+                method: "getOrganizationWallets",
+                params: {
+                    organizationId: this.config.organizationId,
+                    limit: limit || 20,
+                    offset: offset || 0,
+                },
+                timestampMs: Date.now(),
+            };
+            console.log("Fetching wallets for organization:", this.config.organizationId);
+            const response = await this.kmsApi.postKmsRpc(request);
+            const result = response.data.result;
+            console.log(`Fetched ${result.wallets.length} wallets out of ${result.totalCount} total`);
+            return {
+                wallets: result.wallets.map((wallet) => ({
+                    walletId: wallet.walletId,
+                    walletName: wallet.walletName,
+                })),
+                totalCount: result.totalCount,
+                limit: result.limit,
+                offset: result.offset,
+            };
+        }
+        catch (error) {
+            console.error("Failed to get wallets:", error.response?.data || error.message);
+            throw new Error(`Failed to get wallets: ${error.response?.data?.message || error.message}`);
+        }
+    }
 }
 exports.ServerSDK = ServerSDK;
 __exportStar(require("./types"), exports);

package/dist/types.d.ts

@@ -17,3 +17,13 @@ export type Transaction = Uint8Array;
 export interface SignedTransaction {
     rawTransaction: string;
 }
+export interface Wallet {
+    walletId: string;
+    walletName: string;
+}
+export interface GetWalletsResult {
+    wallets: Wallet[];
+    totalCount: number;
+    limit: number;
+    offset: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phantom/server-sdk",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Server SDK for Phantom Wallet",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",